v3.22.7: a raised card error honours the step's on_fail

The runner's step loop caught an exception and hard-coded status "error" +
stop, ignoring on_fail - so a file-read of an absent optional file
(re-verified live on 3.22.6: MF/A153/49AC, note "6a82: Wrong parameters -
File not found", on_fail "warning" still stopped the run) could not express
the "read an optional file" pattern (49AC is documented optional: its
absence means no menu password).

The handler now treats a raised error as a failed "Error" check at the
step's level (the message as actual/detail and the note): on_fail "warning"
warns and the run continues, the default still stops; the drain-if-pending
behaviour is unchanged.  Every raised exception is treated the same - the
two "file absent" raise paths (pySim's SwMatchError for model files and
probe_file's RuntimeError with the decoded SW for custom FIDs) cannot be
told apart by type, and load-time validation (normalise_script) stays
strict.

Docs: the guide's on_fail paragraph and run-errors list (the 6A82 bullet),
api.md and help EN/RU.  Tests: a raising file-read with on_fail "warning"
warns and the next step runs; without on_fail the run still stops.
843 frontend + 821 Python; sw cache simple-v411.

docs/api.md

@@ -753,7 +753,9 @@ step left pending (`91XX`).
 the decoded PoR of this exchange (inline or SEND SHORT MESSAGE; at least one
 field).  `on_fail` is `error` (terminates the script) or `warning` (continues)
 and applies to every step failure - including an expectation that finds no
-pending command (v3.21.0; `warning` is the tolerant consume-if-pending form).
+pending command (v3.21.0; `warning` is the tolerant consume-if-pending form)
+and a card/transport error raised during the step (v3.22.7 - the error is
+reported as a failed `Error` check at the step's level).
 
 **Expectation steps** (`type: "expect"`) require a command pending from the
 previous step (`91XX`); they never poll - a `9000` response means no command

docs/test-scripts.md

@@ -229,8 +229,11 @@ TEST-RUN step 4: MENU-SELECT ENVELOPE=80c2000009d30702020181900101 item=1 ('One'
 Every step may carry `on_fail`: `"error"` (default - stops the run) or
 `"warning"` (continues, the report shows ⚠).  Each entry of `checks` may
 override it with its own `on_fail`.  The level applies to **every** step
-failure, including an expectation that finds no pending command (v3.21.0) -
+failure, including an expectation that finds no pending command (v3.21.0)
-the tolerant "consume a command if there is one" form is an expectation with
+and a **card error raised during the step** (v3.22.7 - an absent optional
+file's `6A82`, a refused SELECT: with `on_fail: "warning"` the step warns,
+the report shows the error as a failed check, and the run continues) - the
+tolerant "consume a command if there is one" form is an expectation with
 `on_fail: "warning"`; to drain and confirm the card is idle, use the
 `proactive-drain` action.
 
@@ -649,6 +652,10 @@ PoR-in-submit (with the transport asserted by the expectation):
   names it).  A `status` action with `attempts > 1` polls until a command
   appears when the card delivers on poll; `on_fail: "warning"` tolerates the
   empty case, and the `proactive-drain` action drains and confirms idle.
+- `6A82: … File not found` (or another raised card error) - the step's
+  `on_fail` decides: the default stops the run, `on_fail: "warning"` warns
+  and continues - the pattern for an **optional** file (`49AC` is documented
+  optional: its absence means no menu password).
 - `menu-select: no menu item matches …` - the error lists the cached menu; a
   miss on an explicit `case_sensitive: true` names the case-insensitive
   candidates.

frontend/help-ru.html

@@ -566,7 +566,7 @@
 	<ul class="list-disc list-inside text-sm space-y-1 mb-3">
 		<li><strong>Действия</strong> &mdash; <em>Envelope</em> (Event Download: сырой тип события + данные, с опциональным переопределением источника &mdash; 82 терминал / 83 сеть) или <em>Event</em> (семантические формы: <strong>та же форма, что и в диалоге отправки на вкладке «Телефон»</strong>, для всех смоделированных событий &mdash; четыре события, которые собирает сервер (Location status, Access technology change, Network rejection, Data connection status change), передаются полями, которые он проверяет и собирает во время запуска, остальные несут собранный формой hex данных события (показывается под формой, с проверкой одного ENVELOPE); источник device identities берётся из события (например, MT call &rarr; сеть) или из его поля источника), <em>Menu Selection</em> (item id 1&ndash;255 или текст пункта с точным/частичным совпадением, по умолчанию без учёта регистра &mdash; выбор <em>«Учёт регистра»</em> в редакторе шагов включает точное совпадение; текст подбирается по меню карты, которое следует за параметрами установки апплета), <em>UPDATE/READ файла</em> (путь + режим; чтение проверяет данные файла), <em>сырой APDU</em> (без авто-обработчика), <em>SCP80</em> (C-APDU или готовый защищённый пакет, опциональные переопределения номера keyset (kvn) / TAR / SPI1 / SPI2 и формат команды &mdash; компактный или обёрнутый в шаблон Command Scripting TS 102 226 &sect;5.2.1 <em>expanded</em> (AA) / <em>expanded AE&nbsp;80</em>; ключи и счётчик берутся из пресета карты, подобранного по ICCID подключённой карты &mdash; запуск называет пресет в хранилище, поэтому всегда используются его keysets, TAR и счётчик &mdash; а сервер сохраняет потреблённый счётчик в пресет по ходу запуска), <em>STATUS</em> (при <em>попытках</em> &gt; 1 опрашивает, пока карта не объявит команду) и <em>Очистка очереди проактивных команд</em> (опрос STATUS и поглощение всех объявленных команд &mdash; результат TERMINAL RESPONSE для каждой, опционально другой результат для первой; граница попыток/интервала; опциональная проверка <em>require</em> по поглощённому.  Пустой опрос проходит, финальный STATUS должен быть idle, а оставшаяся команда передаётся следующему шагу &mdash; используйте в начале, середине или конце скрипта, чтобы убедиться, что карта перестала слать команды; она же поглощает команду, оставшуюся от предыдущего шага (ответившего <code class="font-mono text-sm">91XX</code>)). У каждого действия есть проверка ответа: ожидаемые SW и данные (точно или маска с подстановкой <code class="font-mono text-sm">?</code> &mdash; <code class="font-mono text-sm">91??</code>) и проверка PoR для SCP80 (<em>любой / без PoR / por_ok</em> или своя проверка декодированного PoR &mdash; статус / SW / данные; транспорт через SEND SHORT MESSAGE работает так же).</li>
 		<li><strong>Ожидания</strong> &mdash; карта должна объявить проактивную команду на предыдущем шаге (SW <code class="font-mono text-sm">91XX</code>, TS 102 221 &sect;7.4.2.1 / TS 102 223 &sect;6.3); <code class="font-mono text-sm">9000</code> означает &laquo;команды нет&raquo;: шаг падает на своём уровне ошибок &mdash; Ошибка останавливает скрипт, Предупреждение продолжает (терпимая форма &laquo;поглотить команду, если она есть&raquo;) &mdash; а действие STATUS с <em>попытками</em> &gt; 1 опрашивает, когда апплет выдаёт команду при опросе. Проверяются тип команды, квалификатор и содержимое: текст / пункт / raw, проверка <em>Alpha</em> (идентификатор Alpha команды, тег <code class="font-mono text-sm">05</code>/<code class="font-mono text-sm">85</code> &mdash; отличается от текстовой строки <code class="font-mono text-sm">8D</code>), проверка <em>SMS TPDU</em> (submit-TPDU команды SEND SHORT MESSAGE: получатель / PID / DCS / UDL / данные &mdash; для собственного SMS апплета), проверка <em>PoR</em> (SEND SHORT MESSAGE несёт PoR, когда пакет запросил PoR-in-submit, бит SPI2 <code class="font-mono text-sm">20</code>: статус ответа, SW R-APDU и данные ответа; перед этим должен выполниться шаг SCP80 &mdash; SW R-APDU находится <em>внутри</em> полезной нагрузки ответа: собственный TAR апплета возвращает данные приложения, поэтому проверяйте данные, а SW оставляйте пустым; отклонённый ENVELOPE (<code class="font-mono text-sm">62XX</code>/<code class="font-mono text-sm">63XX</code>) может вовсе не нести пакет ответа &mdash; для такого шага оставляйте проверку PoR «любой» или ожидайте «без PoR») и проверка <em>Files</em> (File List команды REFRESH, например квалификатор <code class="font-mono text-sm">00</code> = NAA initialization with full file change notification). <strong>TERMINAL RESPONSE</strong> (результат, идентификатор пункта, текст, доп. TLV) является частью инструкции.</li>
-		<li><strong>Уровни ошибок</strong> &mdash; несовпадение помечает шаг как <em>Ошибка</em> (скрипт останавливается) или <em>Предупреждение</em> (продолжает); уровень применяется к любой ошибке шага, включая ожидание без объявленной команды; каждая проверка показывается с ожидаемым и фактическим значением.</li>
+		<li><strong>Уровни ошибок</strong> &mdash; несовпадение помечает шаг как <em>Ошибка</em> (скрипт останавливается) или <em>Предупреждение</em> (продолжает); уровень применяется к любой ошибке шага, включая ожидание без объявленной команды и ошибку карты, возникшую на шаге (например, <code class="font-mono text-sm">6A82</code> отсутствующего необязательного файла); каждая проверка показывается с ожидаемым и фактическим значением.</li>
 		<li><strong>Шаблоны</strong> &mdash; Empty, <em>Обзор меню STK</em>, <em>Апплет через SCP80</em>; редактор шагов — формный (действие Event показывает форму события из симулятора), а набор экспортируется/импортируется пакетом JSON (набор и его скрипты).</li>
 	</ul>
 	<p class="text-sm mb-3">Каждый шаг пишет семантическую строку в журнал сервера под своим номером (<code class="font-mono text-sm">TEST-RUN step N: …</code>), запрос перед ответом: отправленный APDU/данные и полученный SW, для SCP80 — открытый C-APDU, собранный защищённый пакет и R-APDU из PoR, для ожидания — тройка FETCH / команда / TERMINAL RESPONSE, очистка очереди проактивных команд — каждый раунд STATUS/FETCH/команда/TR, а очистка в конце запуска — поглощённые команды (отвечаются <code class="font-mono text-sm">ok</code> &mdash; cancel отправляется только по явному запросу скрипта), а для выбора пункта меню — полный ENVELOPE с определённым пунктом. Запустите сервер с <code class="font-mono text-sm">--apdu-trace</code>, чтобы добавить и журнал сырых транспортных APDU.</p>

frontend/help.html

@@ -565,7 +565,7 @@
 	<ul class="list-disc list-inside text-sm space-y-1 mb-3">
 		<li><strong>Actions</strong> &mdash; <em>Envelope</em> (Event Download: raw event type + data, with an optional source override &mdash; 82 terminal / 83 network) or <em>Event</em> (the semantic forms: the <strong>same form the Phone tab's send dialog uses</strong>, for every modelled event &mdash; the four events the server builds (Location status, Access technology change, Network rejection, Data connection status change) travel as fields it validates and builds at run time, every other event carries the form's built event-data hex (shown live under the form, with the one-ENVELOPE check); the device-identities source comes from the event (e.g. MT call &rarr; network) or its source field), <em>Menu Selection</em> (item id 1&ndash;255, or the item's text with an exact/contains match, case-insensitive by default &mdash; the step editor's <em>Match case</em> choice switches to an exact-case match; the text is resolved against the card's menu, which follows the applet's install parameters), <em>UPDATE/READ file</em> (path + mode; reads verify the file data), <em>raw APDU</em> (no auto-handler), <em>SCP80</em> (C-APDU or a pre-built secured packet, optional keyset number (kvn) / TAR / SPI1 / SPI2 overrides and a command format &mdash; compact, or the TS 102 226 &sect;5.2.1 Command Scripting template <em>expanded</em> (AA) / <em>expanded AE&nbsp;80</em> around the C-APDU; the keys and the counter come from the card preset matched by the equipped card's ICCID &mdash; the run names the stored preset, so it always uses its keysets, TARs and counter &mdash; the server persists the consumed counter into it as the run proceeds), <em>STATUS</em> (with <em>attempts</em> &gt; 1 it polls until the card announces a command) and <em>Proactive drain</em> (poll STATUS and consume every announced command &mdash; the TERMINAL RESPONSE result for each, optionally a different result for the first; the attempt/interval bound; an optional <em>require</em> assertion over what was drained.  An empty poll passes, the final STATUS must be idle, and a still-pending command is handed to the next step &mdash; use it at the start, in the middle or at the end of a script to make sure the card has stopped sending; it also consumes a command a previous step left pending (a step that answered <code class="font-mono text-sm">91XX</code>). Every action has a response check: expected SW and data (exact, or a mask with <code class="font-mono text-sm">?</code> nibble wildcards &mdash; <code class="font-mono text-sm">91??</code>) plus a PoR check for SCP80 (<em>any / no PoR / por_ok</em>, or a custom assertion of the decoded PoR &mdash; status / SW / data; the SEND SHORT MESSAGE transport works the same).</li>
 		<li><strong>Expectations</strong> &mdash; the card must have announced a proactive command in the previous step (SW <code class="font-mono text-sm">91XX</code>, TS 102 221 &sect;7.4.2.1 / TS 102 223 &sect;6.3); a <code class="font-mono text-sm">9000</code> means &ldquo;no command&rdquo;: the step fails at its fail level &mdash; Error stops the script, Warning continues (the tolerant &ldquo;consume a command if there is one&rdquo; form) &mdash; and a STATUS action with <em>attempts</em> &gt; 1 polls when the applet delivers on poll. The command type, qualifier and contents are verified: text / item / raw checks, an <em>Alpha</em> check (the command's Alpha identifier, tag <code class="font-mono text-sm">05</code>/<code class="font-mono text-sm">85</code> &mdash; distinct from the <code class="font-mono text-sm">8D</code> text string), an <em>SMS TPDU</em> check (the submit TPDU of a SEND SHORT MESSAGE: destination / PID / DCS / UDL / user data &mdash; for an applet's own SMS), a <em>PoR</em> check (a SEND SHORT MESSAGE carries the PoR when the packet requested PoR-in-submit, SPI2 bit <code class="font-mono text-sm">20</code>: the response status, the R-APDU SW and the response data; make sure an SCP80 step ran first &mdash; the R-APDU SW lives <em>inside</em> the response payload: an applet's own TAR returns application data, so check its data and leave the SW empty; a refused ENVELOPE (<code class="font-mono text-sm">62XX</code>/<code class="font-mono text-sm">63XX</code>) may carry no response packet at all &mdash; leave the PoR check at <em>any</em> or expect <em>no PoR</em> for such a step) and a <em>Files</em> check (the File List of a REFRESH, e.g. qualifier <code class="font-mono text-sm">00</code> = NAA initialization with full file change notification). The scripted <strong>TERMINAL RESPONSE</strong> (result, item identifier, text, extra TLVs) is part of the instruction.</li>
-		<li><strong>Fail levels</strong> &mdash; a mismatch flags the step as <em>Error</em> (terminates the script) or <em>Warning</em> (continues); every step failure honours it, including an expectation that finds no pending command; each check is reported with expected vs actual values.</li>
+		<li><strong>Fail levels</strong> &mdash; a mismatch flags the step as <em>Error</em> (terminates the script) or <em>Warning</em> (continues); every step failure honours it, including an expectation that finds no pending command and a card error raised during the step (an absent optional file's <code class="font-mono text-sm">6A82</code>); each check is reported with expected vs actual values.</li>
 		<li><strong>Templates</strong> &mdash; Empty, <em>STK menu browsing</em>, <em>Applet via SCP80</em>; the step editor is form-based (the event action renders the Simulator's event form), and a suite exports/imports as a JSON bundle (the suite plus its scripts).</li>
 	</ul>
 	<p class="text-sm mb-3">Every step logs a semantic line to the server log under its step number (<code class="font-mono text-sm">TEST-RUN step N: …</code>), request before response: the APDU/data sent and the SW received, for SCP80 the plaintext C-APDU, the built secured packet and the PoR's R-APDU, for an expectation the FETCH / command / TERMINAL RESPONSE trio, a proactive drain every STATUS/FETCH/command/TR round and the run cleanup the commands it drained (answered <code class="font-mono text-sm">ok</code> &mdash; a cancel is only sent when a script asks for it), and for a menu selection the complete ENVELOPE with the resolved item. Start the server with <code class="font-mono text-sm">--apdu-trace</code> to add the raw transport APDU log as well.</p>

frontend/index.html

@@ -1903,7 +1903,7 @@
 // ===== Version =====
 // Single source of truth for the PWA version: shown in the header and used
 // by the server version check in pysimConnect().
-const SIMPLE_VERSION = '3.22.6';
+const SIMPLE_VERSION = '3.22.7';
 document.getElementById('app-version').textContent = 'v' + SIMPLE_VERSION;
 
 // ===== view history (the browser Back/Forward buttons) =====

frontend/sw.js

@@ -1,4 +1,4 @@
-const CACHE = 'simple-v410';
+const CACHE = 'simple-v411';
 const URLS = [
   'index.html',
   'help.html',

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pysim-simple-server"
-version = "3.22.6"
+version = "3.22.7"
 description = "HTTP REST server wrapping pysim for the SIMple PWA"
 requires-python = ">=3.8"
 # pysim is a git-only dependency installed explicitly by setup.bat/setup.sh.

pysim_simple_server/server.py

@@ -36,7 +36,7 @@ from osmocom.tlv import BER_TLV_IE
 from osmocom.utils import rpad
 
 
-VERSION = '3.22.6'
+VERSION = '3.22.7'
 
 MAX_ENVELOPE_SEGMENTS = 5  # max SMS segments for outgoing C-APDU in ENVELOPE
 
@@ -7124,16 +7124,25 @@ def _test_run_script(server, script, preset, shared=None):
                 # Error terminates the script; Warning and OK continue.
                 break
         except Exception as e:
-            _test_entry_update(entry, {
+            # A raised card/transport error is a step failure like any other:
-                'status': 'error', 'note': str(e),
+            # it honours the step's on_fail (v3.22.7).  An absent optional
-                'ms': int((time.time() - entry['started']) * 1000)})
+            # file (6A82), a refused SELECT or a preset/keyset error then
-            sys.stderr.write('TEST-RUN step %d failed: %s\n' % (index + 1, e))
+            # warns and the run continues, with the error as a failed check;
+            # the default (error) still stops the run.
+            level = step.get('on_fail') or 'error'
+            check = _test_check_result('Error', False, 'the step to run',
+                                       str(e), level, detail=str(e))
+            _test_finish_entry(entry, {'status': level, 'checks': [check],
+                                       'note': str(e)})
+            sys.stderr.write('TEST-RUN step %d failed (%s): %s\n'
+                             % (index + 1, level, e))
             if pending is not None:
                 with _CARD_LOCK:
                     drained = _test_drain_pending(scc, pending)
                 _test_entry_update(entry, {k: v for k, v in drained.items() if k != 'note'})
                 pending = None
-            break
+            if level == 'error':
+                break
     if pending is not None:
         with _CARD_LOCK:
             drained = _test_drain_pending(scc, pending)

tests/test_testscript.py

@@ -1690,6 +1690,50 @@ class TestRunnerActions(RunnerTestCase):
         self.assertEqual(lchan.written, 'AA55')
         self.assertEqual(run['steps'][1]['data'], 'AA55')
 
+    def test_a_raised_card_error_honours_on_fail(self):
+        # v3.22.7: a card error raised during a step (an absent optional
+        # file's 6A82, a refused SELECT) is a step failure like any other -
+        # on_fail "warning" warns and the run continues.
+        lchan = object()          # _select_path (patched) raises before its use
+        server = FakeServer(FakeScc())
+        server.app = type('App', (), {'rs': type('Rs', (), {'lchan': [lchan]})()})()
+        server.scc.push('80F2', '', '9000')
+        with mock.patch.object(S, '_select_path', side_effect=RuntimeError(
+                '6a82: Wrong parameters - File not found')):
+            run = self.run_script(server, [
+                {'type': 'action', 'kind': 'file-read',
+                 'params': {'path': 'MF/A153/49AC'}, 'on_fail': 'warning'},
+                {'type': 'action', 'kind': 'status', 'params': {}},
+            ])
+        self.assertEqual(run['status'], 'warning', run['steps'])
+        self.assertEqual(len(run['steps']), 2)
+        entry = run['steps'][0]
+        self.assertEqual(entry['status'], 'warning')
+        self.assertIn('6a82', entry['note'])
+        check = entry['checks'][0]
+        self.assertEqual(check['label'], 'Error')
+        self.assertFalse(check['ok'])
+        self.assertEqual(check['level'], 'warning')
+        self.assertIn('6a82', check['actual'])
+        # the following step ran
+        self.assertEqual(run['steps'][1]['status'], 'ok')
+
+    def test_a_raised_card_error_still_stops_by_default(self):
+        lchan = object()          # _select_path (patched) raises before its use
+        server = FakeServer(FakeScc())
+        server.app = type('App', (), {'rs': type('Rs', (), {'lchan': [lchan]})()})()
+        with mock.patch.object(S, '_select_path', side_effect=RuntimeError(
+                '6a82: Wrong parameters - File not found')):
+            run = self.run_script(server, [
+                {'type': 'action', 'kind': 'file-read',
+                 'params': {'path': 'MF/A153/49AC'}},
+                {'type': 'action', 'kind': 'status', 'params': {}},
+            ])
+        self.assertEqual(run['status'], 'error', run['steps'])
+        self.assertEqual(len(run['steps']), 1)
+        self.assertEqual(run['steps'][0]['status'], 'error')
+        self.assertIn('6a82', run['steps'][0]['note'])
+
     def test_run_guard_blocks_card_endpoints_only(self):
         S._TEST_RUNNING = True
         try: