nvda-addon-testkit 0.1.3__tar.gz → 1.1.0__tar.gz

{nvda_addon_testkit-0.1.3 → nvda_addon_testkit-1.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: nvda-addon-testkit
-Version: 0.1.3
+Version: 1.1.0
 Summary: End-to-end testing for NVDA add-ons against a real NVDA
 Project-URL: Homepage, https://github.com/ZirekHQ/nvda-addon-testkit
 Project-URL: Issues, https://github.com/ZirekHQ/nvda-addon-testkit/issues
@@ -44,6 +44,15 @@ def test_my_addon_announces_itself(nvda, addon_under_test):
     nvda.log.assert_no_errors()
 ```
 
+The same test reads as plain steps with the (experimental) DSL:
+
+```python
+def test_my_addon_announces_itself(nvda, addon_under_test):
+    nvda.press("NVDA+shift+m")
+    nvda.should_hear("my add-on is ready")
+    nvda.should_have_no_errors()
+```
+
 ## Install
 
 ```bash
@@ -94,6 +103,25 @@ still on Extended Security Updates).
 | `nvda.log` | structured log records, and `assert_no_errors()` |
 | `nvda.addons` | two-phase install, remove, and state |
 
+`nvda.eval()` runs a single expression inside NVDA; `nvda.exec()` runs a
+full multi-statement scenario and returns whatever it binds to
+`__result__`. Both need `--nvda-allow-eval`. A bad scenario raises
+`ScenarioSyntaxError`, so catching bare `except Exception: pass` around
+either call still swallows it — catch the types you expect instead.
+
+`nvda.restart_harness()` kills and relaunches the NVDA process — use it to
+finish a two-phase add-on install or reset to a clean process. It does not
+exercise NVDA's own restart logic. For that, use `nvda.restart_nvda()`,
+which triggers NVDA's real `core.restart()` and waits for the replacement
+process — needs `--nvda-allow-eval`, since it is built on `nvda.eval()`.
+
+A real `wx.Dialog.ShowModal()` never returns control to any of the above —
+NVDA's main-thread queue doesn't drain while one is up. Open it with
+`nvda.exec_nowait()` instead of `exec()` (queues the scenario without
+waiting for it to finish), then close it with `nvda.simulate_modal(gesture,
+timeout=10.0)`, which sends real injected keyboard input once our process
+takes the foreground.
+
 ## Requirements
 
 Windows to run the tests. NVDA is downloaded automatically — you do not need
@@ -126,4 +154,4 @@ If this repository saves you time and effort, please consider supporting it!
 
 - ⭐ [Star on GitHub](https://github.com/ZirekHQ/nvda-addon-testkit)
 - 🐦 [Share on Twitter](https://twitter.com/intent/tweet?text=nvda-addon-testkit%20-%20real%20end-to-end%20testing%20for%20NVDA%20add-ons&url=https%3A%2F%2Fgithub.com%2FZirekHQ%2Fnvda-addon-testkit)
-- 💖 [More ways to support](https://github.com/ZirekHQ) — Open Collective coming soon
+- 💖 [Support on Open Collective](https://opencollective.com/zirek)

{nvda_addon_testkit-0.1.3 → nvda_addon_testkit-1.1.0}/README.md

@@ -17,6 +17,15 @@ def test_my_addon_announces_itself(nvda, addon_under_test):
     nvda.log.assert_no_errors()
 ```
 
+The same test reads as plain steps with the (experimental) DSL:
+
+```python
+def test_my_addon_announces_itself(nvda, addon_under_test):
+    nvda.press("NVDA+shift+m")
+    nvda.should_hear("my add-on is ready")
+    nvda.should_have_no_errors()
+```
+
 ## Install
 
 ```bash
@@ -67,6 +76,25 @@ still on Extended Security Updates).
 | `nvda.log` | structured log records, and `assert_no_errors()` |
 | `nvda.addons` | two-phase install, remove, and state |
 
+`nvda.eval()` runs a single expression inside NVDA; `nvda.exec()` runs a
+full multi-statement scenario and returns whatever it binds to
+`__result__`. Both need `--nvda-allow-eval`. A bad scenario raises
+`ScenarioSyntaxError`, so catching bare `except Exception: pass` around
+either call still swallows it — catch the types you expect instead.
+
+`nvda.restart_harness()` kills and relaunches the NVDA process — use it to
+finish a two-phase add-on install or reset to a clean process. It does not
+exercise NVDA's own restart logic. For that, use `nvda.restart_nvda()`,
+which triggers NVDA's real `core.restart()` and waits for the replacement
+process — needs `--nvda-allow-eval`, since it is built on `nvda.eval()`.
+
+A real `wx.Dialog.ShowModal()` never returns control to any of the above —
+NVDA's main-thread queue doesn't drain while one is up. Open it with
+`nvda.exec_nowait()` instead of `exec()` (queues the scenario without
+waiting for it to finish), then close it with `nvda.simulate_modal(gesture,
+timeout=10.0)`, which sends real injected keyboard input once our process
+takes the foreground.
+
 ## Requirements
 
 Windows to run the tests. NVDA is downloaded automatically — you do not need
@@ -99,4 +127,4 @@ If this repository saves you time and effort, please consider supporting it!
 
 - ⭐ [Star on GitHub](https://github.com/ZirekHQ/nvda-addon-testkit)
 - 🐦 [Share on Twitter](https://twitter.com/intent/tweet?text=nvda-addon-testkit%20-%20real%20end-to-end%20testing%20for%20NVDA%20add-ons&url=https%3A%2F%2Fgithub.com%2FZirekHQ%2Fnvda-addon-testkit)
-- 💖 [More ways to support](https://github.com/ZirekHQ) — Open Collective coming soon
+- 💖 [Support on Open Collective](https://opencollective.com/zirek)

{nvda_addon_testkit-0.1.3 → nvda_addon_testkit-1.1.0}/docs/modules/ROOT/examples/tests_e2e/conftest.py

@@ -65,3 +65,9 @@ def check_no_unexpected_errors(client, *, since: int = 0) -> None:
 @pytest.fixture
 def assert_no_unexpected_errors():
     return check_no_unexpected_errors
+
+
+@pytest.fixture
+def require_eval(pytestconfig):
+    if not pytestconfig.option.nvda_allow_eval:
+        pytest.skip("needs --nvda-allow-eval")

{nvda_addon_testkit-0.1.3 → nvda_addon_testkit-1.1.0}/docs/modules/ROOT/examples/tests_e2e/test_demo_addon.py

@@ -27,19 +27,19 @@ def test_install_is_two_phase_and_completes_on_restart(
     assert info.name == "testkit-demo"
     assert nvda.addons.state("testkit-demo") is AddonState.PENDING_INSTALL
 
-    nvda.restart()
+    nvda.restart_harness()
     assert nvda.addons.state("testkit-demo") is AddonState.ENABLED
     assert_no_unexpected_errors(nvda)
 
     nvda.addons.remove("testkit-demo")
-    nvda.restart()
+    nvda.restart_harness()
     assert nvda.addons.state("testkit-demo") is AddonState.NOT_INSTALLED
     # end::addons[]
 
 
 def test_the_installed_addon_logs_at_startup(nvda, addon_under_test):
     # tag::log[]
-    nvda.restart()
+    nvda.restart_harness()
     nvda.log.wait_for(re.escape(STARTUP_MESSAGE), since=0, timeout=20)
     # end::log[]
 
@@ -53,7 +53,7 @@ def test_its_gesture_produces_the_expected_speech(nvda, addon_under_test):
 
 def test_it_survives_a_restart(nvda, addon_under_test):
     # tag::fixtures[]
-    nvda.restart()
+    nvda.restart_harness()
     assert nvda.addons.state("testkit-demo") is AddonState.ENABLED
     before = nvda.speech.index()
     nvda.keys.press("NVDA+shift+control+d")
@@ -66,5 +66,5 @@ def test_removal_is_also_two_phase(nvda, addon_under_test):
     and that session-scoped fixture will not reinstall it."""
     nvda.addons.remove("testkit-demo")
     assert nvda.addons.state("testkit-demo") is AddonState.PENDING_REMOVE
-    nvda.restart()
+    nvda.restart_harness()
     assert nvda.addons.state("testkit-demo") is AddonState.NOT_INSTALLED

nvda_addon_testkit-1.1.0/docs/modules/ROOT/examples/tests_e2e/test_demo_dsl.py

@@ -0,0 +1,63 @@
+"""The demo add-on driven through the DSL. Each tagged block is a docs example.
+
+This file assumes the demo add-on is not installed when it starts: test_demo_addon.py,
+sorted earlier, uninstalls it last.
+"""
+
+import pytest
+
+# Mirrors RUNNER_ENVIRONMENT_ERRORS in tests_e2e/conftest.py.
+RUNNER_NOISE = (
+    r"nvwave|WASAPI|audio (?:device|output|session|endpoint)",
+    r"synthDriver|synthesi[sz]|espeak|oneCore|SAPI",
+    r"braille ?display|brailleDisplayDriver|brailleInput",
+    r"UIAHandler|IAccessible|interactive desktop|desktop object",
+)
+
+
+@pytest.mark.fresh_nvda
+def test_install_and_remove_are_one_step_each(nvda):
+    # tag::dsl-lifecycle[]
+    nvda.should_have_addon("testkit-demo", "not installed")
+    nvda.install_addon()
+    nvda.should_have_addon("testkit-demo", "enabled")
+    nvda.remove_addon("testkit-demo")
+    nvda.should_have_addon("testkit-demo", "not installed")
+    # end::dsl-lifecycle[]
+
+
+def test_the_gesture_announces_the_phrase(nvda):
+    nvda.install_addon()
+    # tag::dsl-basic[]
+    nvda.press("NVDA+shift+control+d")
+    nvda.should_hear("testkit demo says hello")
+    # end::dsl-basic[]
+
+
+def test_startup_logs_the_loaded_message(nvda):
+    nvda.install_addon()
+    nvda.relaunch()
+    nvda.should_log("testkit demo add-on loaded", within=20)
+    nvda.should_have_no_errors(ignoring=list(RUNNER_NOISE))
+
+
+def test_the_block_form_waits_for_the_speech_a_step_causes(nvda):
+    nvda.install_addon()
+    # tag::dsl-expecting[]
+    with nvda.expecting_speech("testkit demo says hello"):
+        nvda.press("NVDA+shift+control+d")
+    # end::dsl-expecting[]
+
+
+def test_a_real_dialog_opens_and_closes_in_a_block(require_eval, nvda):
+    # tag::dsl-dialog[]
+    with nvda.dialog(
+        "import wx\n"
+        "dlg = wx.MessageDialog(None, 'confirm?', 'confirm?', wx.YES_NO)\n"
+        "dlg.ShowModal()\n"
+        "dlg.Destroy()\n",
+        close_with="enter",
+    ):
+        pass
+    # end::dsl-dialog[]
+    nvda.wait_until_idle(timeout=15)

nvda_addon_testkit-1.1.0/docs/modules/ROOT/examples/tests_e2e/test_dsl_probes.py

@@ -0,0 +1,29 @@
+"""Probes for DSL behaviour not yet verified on real NVDA."""
+
+import pytest
+
+DIALOG = (
+    "import wx\n"
+    "dlg = wx.MessageDialog(None, 'confirm?', 'confirm?', wx.YES_NO)\n"
+    "dlg.ShowModal()\n"
+    "dlg.Destroy()\n"
+)
+
+
+def test_speech_and_log_reads_work_while_a_modal_is_open(require_eval, nvda):
+    nvda.open_dialog(DIALOG)
+    try:
+        assert isinstance(nvda.speech.index(), int)
+        assert isinstance(nvda.log.all(), list)
+    finally:
+        nvda.close_dialog("enter")
+
+
+@pytest.mark.parametrize("text", ["Hello", "a.b,c", "x!y"])
+def test_typing_characters_beyond_lowercase_letters(nvda, text):
+    nvda.type(text)
+
+
+@pytest.mark.xfail(strict=False, reason="non-ASCII gesture names are unverified")
+def test_typing_non_ascii_characters(nvda):
+    nvda.type("ünï")

nvda_addon_testkit-1.1.0/docs/modules/ROOT/examples/tests_e2e/test_modal_dialog_investigation.py

@@ -0,0 +1,67 @@
+"""Investigation for issue #34, gaps 2 & 5: does a queued main-thread job
+start while a real ShowModal() dialog is up?
+
+This is not a regression test. It is a one-shot probe: run it once on
+Windows CI, read the result, and act on it per the plan (either open a new
+issue describing a real fix, or proceed with the simulate_modal() fallback
+in the next task). Delete or keep this file once the investigation is
+resolved -- it is not meant to run on every CI build.
+
+Everything happens inside a single exec_in_nvda call, entirely on NVDA's
+main thread: the spy's XML-RPC server (server.py) is a plain, unthreaded
+SimpleXMLRPCServer, so two separate RPC connections can never be genuinely
+concurrent at the transport level -- the second call simply can't be
+dispatched until the first's handler returns. Queuing the second job from
+*inside* the running scenario, via queueHandler.queueFunction directly,
+avoids needing RPC-level concurrency at all: it tests whether NVDA's own
+queue-draining mechanism still runs while the main thread is nested inside
+ShowModal()'s event loop, using a timestamp comparison instead of a second
+network round trip.
+
+A third, lower-probability outcome is possible: if the dialog's own
+wx.CallLater dismiss timer never fires for some unrelated reason, this
+scenario never returns from ShowModal(), so nvda.exec() raises an RpcError
+(wrapping exec_in_nvda's server-side "started on NVDA's main thread but did
+not return within 30.0s" timeout) instead of returning a __result__ to
+assert on. If you see that on a real run, it's worth investigating
+separately -- it doesn't confirm or refute the queue-blocking hypothesis
+either way.
+"""
+
+
+def test_a_second_job_while_a_real_modal_is_up(require_eval, nvda):
+    scenario = (
+        "import queueHandler\n"
+        "import time\n"
+        "import wx\n"
+        "job_b_ran_at = []\n"
+        # exec_in_nvda runs this with separate globals/locals dicts (like a
+        # class body), so a nested def can't see job_b_ran_at/time as
+        # globals -- bind both as defaults, evaluated now, in this scope.
+        "def job_b(sink=job_b_ran_at, now=time.monotonic):\n"
+        "    sink.append(now())\n"
+        "queueHandler.queueFunction(queueHandler.eventQueue, job_b)\n"
+        "dlg = wx.MessageDialog(None, 'probe', 'probe', wx.YES_NO)\n"
+        "wx.CallLater(1000, dlg.EndModal, wx.ID_YES)\n"
+        "before = time.monotonic()\n"
+        "dlg.ShowModal()\n"
+        "after = time.monotonic()\n"
+        "dlg.Destroy()\n"
+        "__result__ = {\n"
+        "    'ran_during_modal': bool(job_b_ran_at) and before <= job_b_ran_at[0] <= after,\n"
+        "    'ran_at_all': bool(job_b_ran_at),\n"
+        "}\n"
+    )
+
+    result = nvda.exec(scenario)
+
+    assert result["ran_during_modal"], (
+        "CONFIRMS THE DEADLOCK: a second main-thread job never ran while a "
+        f"real ShowModal() dialog was up (ran_at_all={result['ran_at_all']!r}). "
+        "Proceed with Task 7 (the simulate_modal() fallback)."
+    )
+    # If this assertion passes instead, the queue IS drained during
+    # ShowModal() in this NVDA version: STOP, do not proceed to Task 7, and
+    # open a new issue describing this finding plus what actually blocks
+    # input_api.py's keys_press() from dismissing the dialog (if anything
+    # still does).

{nvda_addon_testkit-0.1.3 → nvda_addon_testkit-1.1.0}/docs/modules/ROOT/examples/tests_e2e/test_smoke.py

@@ -37,5 +37,25 @@ def test_config_round_trips_through_a_real_nvda(nvda):
 
 
 def test_startup_produced_no_errors(nvda, assert_no_unexpected_errors):
-    nvda.restart()
+    nvda.restart_harness()
     assert_no_unexpected_errors(nvda)
+
+
+def test_restart_nvda_exercises_core_restart(require_eval, nvda, assert_no_unexpected_errors):
+    old_pid = nvda.process.handshake.pid
+    nvda.restart_nvda(timeout=60)
+    assert nvda.process.handshake.pid != old_pid
+    assert_no_unexpected_errors(nvda)
+
+
+def test_simulate_modal_closes_a_real_dialog(require_eval, nvda):
+    # tag::modal[]
+    nvda.exec_nowait(
+        "import wx\n"
+        "dlg = wx.MessageDialog(None, 'confirm?', 'confirm?', wx.YES_NO)\n"
+        "dlg.ShowModal()\n"
+        "dlg.Destroy()\n"
+    )
+    assert nvda.simulate_modal("enter", timeout=10)
+    # end::modal[]
+    nvda.wait_until_idle(timeout=15)

{nvda_addon_testkit-0.1.3 → nvda_addon_testkit-1.1.0}/docs/modules/ROOT/nav.adoc

@@ -3,12 +3,14 @@
 * xref:tutorial.adoc[Writing Your First Test]
 * Guide
 ** xref:guide/fixtures.adoc[Fixtures]
+** xref:guide/dsl.adoc[Writing tests with the DSL]
 ** xref:guide/speech.adoc[speech]
 ** xref:guide/braille.adoc[braille]
 ** xref:guide/keys.adoc[keys]
 ** xref:guide/config.adoc[config]
 ** xref:guide/log.adoc[log]
 ** xref:guide/addons.adoc[addons]
+** xref:guide/modal-dialogs.adoc[Closing a real modal dialog]
 * xref:example-project.adoc[Example Project]
 * xref:ci-guide.adoc[Configuring CI]
 * xref:troubleshooting.adoc[Troubleshooting]

nvda_addon_testkit-1.1.0/docs/modules/ROOT/pages/guide/dsl.adoc

@@ -0,0 +1,154 @@
+= Writing tests with the DSL
+
+NOTE: The DSL is experimental. Names may change in minor releases until it is marked stable.
+
+The `nvda` fixture reads as a list of plain steps. Each step is one sentence on one line. Nothing
+needs nesting, and failure messages are plain numbered text with no colour or tables, so they read
+cleanly through a screen reader.
+
+The examples assume the add-on under test is installed. Call `nvda.install_addon()` in the test, or
+request the `addon_under_test` fixture.
+
+[source,python]
+----
+def test_the_gesture_announces_the_phrase(nvda):
+include::example$tests_e2e/test_demo_dsl.py[tag=dsl-basic,indent=4]
+----
+
+== Actions
+
+Actions send input or change NVDA's state. Each one records where speech begins to count for the
+next assertion, so you never pass `since=`.
+
+* `nvda.press("NVDA+t")` sends a gesture.
+* `nvda.type("text")` sends one gesture per character. A character that is not a valid gesture
+  name raises an error that names it.
+* `nvda.relaunch()` kills and relaunches the NVDA process. The add-on stays installed.
+* `nvda.restart_nvda()` runs NVDA's own restart. Needs `--nvda-allow-eval`.
+
+== Assertions
+
+* `nvda.should_hear("text")` waits for speech produced after the last action.
+* `nvda.should_hear(matching=r"\d+:\d+")` does the same with a regular expression.
+* `nvda.should_not_hear("error", for_seconds=1)` watches for a fixed time. Put a `should_hear`
+  before it, and raise `for_seconds` on slow machines.
+* `nvda.should_log("text")` waits for a log record. It searches the log since the test began, or
+  since the last relaunch, because a relaunch starts a new NVDA process with a fresh log. It does
+  not restrict the search to records written after the last action.
+* `nvda.should_have_no_errors()` fails on logged errors. Pass `ignoring=[...]` or set
+  `ignore-log-errors` to skip runner noise.
+* `nvda.should_have_addon("name", "enabled")` checks an add-on's state.
+
+Text matching is plain and case-insensitive, and finds the text anywhere in an utterance. Use
+`matching=` only when you need a regex. A string pattern is searched case-insensitively; a compiled
+pattern keeps its own flags. The wait defaults to 10 seconds. Change it per call with `within=20`,
+or for the project with `timeout = 20` under `[tool.nvda-testkit]`.
+
+Two `should_hear` calls after one action each search all of that action's speech. They do not
+check order, and two identical calls pass on a single occurrence.
+
+== Waiting for speech around a block
+
+[source,python]
+----
+def test_it_speaks_after_the_step(nvda):
+include::example$tests_e2e/test_demo_dsl.py[tag=dsl-expecting,indent=4]
+----
+
+If the block relaunches NVDA, the search covers everything the new process said.
+
+== Add-on lifecycle
+
+Mark the test with `@pytest.mark.fresh_nvda` so it starts from a clean add-on state. The included
+snippet omits the decorator.
+
+[source,python]
+----
+def test_install_and_remove(nvda):
+include::example$tests_e2e/test_demo_dsl.py[tag=dsl-lifecycle,indent=4]
+----
+
+`install_addon()` installs the bundle from the `addon-bundle` setting, or the path you pass, then
+relaunches NVDA and checks that the add-on is enabled. `remove_addon(name)` removes it, relaunches,
+and checks that it is gone. An add-on installed with `install_addon()` is removed again when the
+test ends.
+
+== Dialogs
+
+[source,python]
+----
+def test_a_dialog(nvda):
+include::example$tests_e2e/test_demo_dsl.py[tag=dsl-dialog,indent=4]
+----
+
+`open_dialog()` and `close_dialog()` are the same steps without the block. While a dialog is open,
+the steps that send input or change state raise an error instead of hanging: `press`, `type`,
+`relaunch`, `restart_nvda`, `restart_harness`, `install_addon`, `remove_addon`, `should_have_addon`,
+`expecting_speech` and `open_dialog`. The assertions that only read speech and log (`should_hear`,
+`should_not_hear`, `should_log` and `should_have_no_errors`) are not guarded and work while a dialog
+is open. The low-level passthroughs `exec`, `eval`, `exec_nowait`, `simulate_modal`,
+`wait_until_idle`, `reset` and `keys.*` are not guarded and still block. Needs
+`--nvda-allow-eval`.
+
+A test that ends with a dialog open fails after the kit closes it.
+
+== Teardown
+
+When a test ends, the `nvda` fixture runs three checks in order. With `fail-on-log-errors`, it
+checks the log first. It then closes a leaked dialog. It then removes the add-ons installed with
+`install_addon()`. Every check runs even if an earlier one fails, and the problems are reported
+together as one teardown error.
+
+== Reading failures
+
+A failed `should_hear` states what it expected, the action before it, the time waited, and what was
+heard, numbered, one item per line:
+
+----
+Expected to hear "PM" within 10 seconds after pressing NVDA+t.
+Time elapsed: 10.05 seconds.
+Heard since that action, 2 items:
+1. "12 colon 00"
+2. "Tuesday"
+Nothing matched. Matching is case-insensitive plain text; use matching= for a regex.
+----
+
+Long lists in `should_hear` and `should_log` messages show ten items. `should_have_no_errors` shows
+six unexpected and three ignored records. Run with `--nvda-verbose` to see all of them. For
+terminal output without colour, run `pytest --color=no`.
+
+== Before and after
+
+Without the DSL:
+
+[source,python]
+----
+before = nvda.speech.index()
+nvda.keys.press("NVDA+t")
+found = nvda.speech.wait_for("12:00", timeout=10, since=before)
+assert "12:00" in found.text
+----
+
+With it:
+
+[source,python]
+----
+nvda.press("NVDA+t")
+nvda.should_hear("12:00")
+----
+
+The old API keeps working, and `nvda.speech`, `nvda.keys` and the other namespaces are still there.
+
+== Project settings
+
+[source,toml]
+----
+[tool.nvda-testkit]
+timeout = 20
+fail-on-log-errors = true
+ignore-log-errors = ["nvwave", "WASAPI"]
+----
+
+With `fail-on-log-errors`, every test that uses `nvda` reports a teardown error if NVDA logged an
+unignored error. Each `ignore-log-errors` entry is a regular expression, searched
+case-insensitively.

nvda_addon_testkit-1.1.0/docs/modules/ROOT/pages/guide/modal-dialogs.adoc

@@ -0,0 +1,48 @@
+= Closing a real modal dialog
+
+`nvda.exec()` and `nvda.eval()` both dispatch through NVDA's own main-thread
+queue and wait for the scenario to finish. That works for anything that
+returns on its own, but a real `wx.Dialog.ShowModal()` never drains that
+queue for as long as it's up — confirmed against a real NVDA, not just
+suspected. A scenario that opens one and waits for `exec()` to return will
+sit there until `exec()`'s own timeout fires, with the dialog still open
+afterwards. `nvda.keys.press()` can't reach it either, for the same reason:
+it dispatches through the same queue.
+
+The dialog's own message loop is still alive, though — it has to be, to
+receive the click a real user would make. `exec_nowait()` and
+`simulate_modal()` reach it that way instead.
+
+[source,python]
+----
+def test_simulate_modal_closes_a_real_dialog(nvda):
+include::example$tests_e2e/test_smoke.py[tag=modal,indent=4]
+----
+
+`exec_nowait()` queues a scenario the same way `exec()` does, but returns
+immediately instead of waiting for it to finish — freeing this process's
+single-threaded RPC server to accept the next call while the scenario is
+stuck inside `ShowModal()`. A syntax error in the scenario still raises
+`ScenarioSyntaxError` synchronously, the same as `exec()`; only running the
+scenario is deferred.
+
+`simulate_modal(gesture, timeout=10.0)` then runs on that next call's own
+thread, never touching the blocked queue: it polls for our own process to
+take the foreground — what a modal dialog does unconditionally on showing —
+and, once it does, sends `gesture` as real injected keyboard input via
+Win32's `SendInput`, the same path a human's keypress takes. It returns
+`False` on a timeout instead of raising, since that usually means the
+scenario never actually opened a dialog rather than NVDA hanging.
+`gesture` is one of `"enter"`, `"escape"`, `"tab"`, `"space"`, `"yes"`, or
+`"no"`.
+
+`exec_nowait()` needs `--nvda-allow-eval`, the same as `eval()`/`exec()`,
+because it runs arbitrary code inside NVDA. `simulate_modal()` does not need
+this flag because it only injects keyboard input.
+
+Pair the two: `exec_nowait()` to open the dialog, `simulate_modal()` to
+close it. `exec_nowait()` records which window is in the foreground before it
+queues the scenario, and the next `simulate_modal()` call treats only a
+different window as the dialog. Calling `exec()` instead of `exec_nowait()`
+to open the dialog defeats the point — `simulate_modal()`'s call would never
+even be dispatched.

{nvda_addon_testkit-0.1.3 → nvda_addon_testkit-1.1.0}/docs/modules/ROOT/pages/troubleshooting.adoc

@@ -63,7 +63,7 @@ the current one; clean it out or narrow the pattern.
 fails.
 
 Install is two-phase by design — `install()` only reaches
-`PENDING_INSTALL`; a call to `nvda.restart()` is what completes it. See
+`PENDING_INSTALL`; a call to `nvda.restart_harness()` is what completes it. See
 xref:guide/addons.adoc[].
 
 == Speech assertion mismatches

{nvda_addon_testkit-0.1.3 → nvda_addon_testkit-1.1.0}/spy/globalPlugins/nvda_testkit_spy/__init__.py

@@ -17,6 +17,7 @@ from . import braille_tap, log_tap, speech_tap
 from . import config_api as config_api
 from . import eval_api as eval_api
 from . import input_api as input_api
+from . import modal_api as modal_api
 from .server import SpyServer
 
 

nvda_addon_testkit-1.1.0/spy/globalPlugins/nvda_testkit_spy/eval_api.py

@@ -0,0 +1,81 @@
+# coding: utf-8
+"""Run code inside NVDA's own process: one expression, or a scenario.
+
+The host refuses to call either unless the session opted in, so the spy does
+not second-guess it: the point is to reach NVDA's live state, which means
+full builtins and real imports. Both run on the main thread for the same
+reason every other mutation does.
+
+eval_in_nvda evaluates a single expression and returns its value.
+exec_in_nvda runs one or more statements and returns whatever the code bound
+to a name called __result__, or None if it bound nothing -- multi-statement
+scenarios (e.g. "import core; core.restart()") do not compile under eval()
+and previously needed an unreadable immediately-invoked-lambda workaround.
+
+exec_in_nvda_nowait queues a scenario onto the main thread like exec_in_nvda
+does, but does not wait for it to finish before returning. Use it for a
+scenario that opens a real modal dialog: exec_in_nvda would block this
+process's single-threaded RPC server for the dialog's whole lifetime, so a
+paired simulate_modal call (see modal_api.py) could never even be
+dispatched to close it.
+"""
+
+import builtins
+
+import queueHandler
+from logHandler import log
+
+from .mainthread import run_on_main_thread
+from .modal_api import remember_foreground_baseline
+from .registry import rpc_method
+
+_SCALARS = (str, int, float, bool, type(None))
+
+
+def _marshallable(value):
+    """xmlrpc carries scalars and containers of scalars; everything else is a repr."""
+    if isinstance(value, _SCALARS):
+        return value
+    if isinstance(value, dict):
+        return {str(key): _marshallable(item) for key, item in value.items()}
+    if isinstance(value, (list, tuple, set, frozenset)):
+        return [_marshallable(item) for item in value]
+    return repr(value)
+
+
+def _evaluate(source):
+    return eval(source, {"__builtins__": builtins})
+
+
+@rpc_method
+def eval_in_nvda(source, timeout=30.0):
+    return _marshallable(run_on_main_thread(lambda: _evaluate(source), timeout=timeout))
+
+
+def _execute(source):
+    scope = {"__builtins__": builtins}
+    exec(compile(source, "<nvda-testkit>", "exec"), scope)
+    return scope.get("__result__")
+
+
+@rpc_method
+def exec_in_nvda(source, timeout=30.0):
+    return _marshallable(run_on_main_thread(lambda: _execute(source), timeout=timeout))
+
+
+@rpc_method
+def exec_in_nvda_nowait(source):
+    # Compiled here, synchronously, so a SyntaxError still surfaces on this
+    # call the same way exec_in_nvda's does -- only *running* the scenario
+    # (which may never return, if it opens a modal dialog) gets queued.
+    code = compile(source, "<nvda-testkit>", "exec")
+
+    def _run():
+        try:
+            exec(code, {"__builtins__": builtins})
+        except Exception:
+            log.error("nvda-testkit: exec_in_nvda_nowait scenario raised", exc_info=True)
+
+    remember_foreground_baseline()
+    queueHandler.queueFunction(queueHandler.eventQueue, _run)
+    return True