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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: nvda-addon-testkit
-Version: 1.0.0
+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
@@ -106,6 +115,13 @@ 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
@@ -138,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-1.0.0 → 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
@@ -79,6 +88,13 @@ 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
@@ -111,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-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.0.0 → nvda_addon_testkit-1.1.0}/docs/modules/ROOT/examples/tests_e2e/test_smoke.py

@@ -46,3 +46,16 @@ def test_restart_nvda_exercises_core_restart(require_eval, nvda, assert_no_unexp
     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-1.0.0 → 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-1.0.0 → 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.0.0 → nvda_addon_testkit-1.1.0}/spy/globalPlugins/nvda_testkit_spy/eval_api.py

@@ -11,11 +11,22 @@ 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))
@@ -50,3 +61,21 @@ def _execute(source):
 @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