nvda-addon-testkit 0.1.0__tar.gz

nvda_addon_testkit-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,77 @@
+name: Bug report
+description: Something in the testkit isn't behaving the way it should.
+title: "[Bug] "
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to report a bug. The fields below help reproduce and diagnose the problem quickly — please fill in as much as you can.
+
+  - type: input
+    id: testkit-version
+    attributes:
+      label: nvda-addon-testkit version
+      description: Output of `nvda-testkit --version`, or the version pinned in your requirements.
+      placeholder: e.g. 0.1.0
+    validations:
+      required: true
+
+  - type: input
+    id: nvda-channel
+    attributes:
+      label: NVDA channel / version under test
+      description: Whatever you passed as `nvda-channel`, or the resolved version from `nvda-testkit doctor`.
+      placeholder: e.g. stable / alpha / 2026.1.1
+    validations:
+      required: true
+
+  - type: input
+    id: os
+    attributes:
+      label: OS
+      description: The e2e suite only runs on Windows; host/spy tests run anywhere. Note which you were running.
+      placeholder: e.g. Windows 11 24H2 (x64) / Ubuntu 24.04 (host tests only)
+    validations:
+      required: true
+
+  - type: textarea
+    id: steps
+    attributes:
+      label: Steps to reproduce
+      description: What did you run, step by step? A minimal failing test or `pytest` invocation is ideal.
+      placeholder: |
+        1. pip install -e ".[dev]"
+        2. pytest tests_e2e/test_smoke.py -v
+        3. ...
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+      placeholder: What you thought would happen.
+    validations:
+      required: true
+
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual behavior
+      placeholder: What actually happened. Include the pytest failure/traceback verbatim.
+    validations:
+      required: true
+
+  - type: textarea
+    id: logs
+    attributes:
+      label: Relevant output
+      description: Full traceback, `nvda.log` records around the failure, or `nvda-testkit doctor` output.
+      render: text
+
+  - type: textarea
+    id: extra
+    attributes:
+      label: Anything else?
+      description: Workarounds you tried, related issues, your `[tool.nvda-testkit]` config, etc.

nvda_addon_testkit-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Usage / configuration help
+    url: https://github.com/ZirekHQ/nvda-addon-testkit/blob/main/README.md
+    about: Start here for install, configuration, and fixture reference.

nvda_addon_testkit-0.1.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,38 @@
+name: Feature request
+description: Suggest a new fixture, namespace, or improvement to existing behavior.
+title: "[Feature] "
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for the suggestion. A bit of context helps decide whether and how to prioritize it.
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: What problem does this solve?
+      description: Describe what you're trying to test or automate, not just the API you have in mind. This often suggests a simpler fixture or a better fit with an existing namespace.
+      placeholder: e.g. "I want to assert on the content of a specific braille cell range, not just the full display buffer..."
+    validations:
+      required: true
+
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed behavior
+      description: What should change? If you have a specific fixture/API shape in mind, sketch it.
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: Other approaches you tried, or existing workarounds using the current fixtures.
+
+  - type: textarea
+    id: extra
+    attributes:
+      label: Anything else?
+      description: Links to similar testing APIs elsewhere, example add-on code this would help test, etc.

nvda_addon_testkit-0.1.0/.github/pull_request_template.md

@@ -0,0 +1,15 @@
+Closes #<!-- issue number, or remove this line if no issue -->.
+
+## Summary
+
+<!-- 1-3 sentences on what this PR does and why. -->
+
+## Changes
+
+<!-- Concrete list of changes. File paths and line refs help reviewers. -->
+
+## Test plan
+
+- [ ] `pytest` passes (host + spy suites).
+- [ ] `ruff check .` / `ruff format --check .` pass.
+- [ ] `tests_e2e/` verified on Windows, if this touches the wire protocol or fixtures. <!-- remove if not applicable -->

nvda_addon_testkit-0.1.0/.github/release-drafter.yml

@@ -0,0 +1,36 @@
+# Release Drafter config. Maintains a draft release on GitHub that auto-updates
+# as PRs merge into main. At release time, open the draft, confirm/adjust the
+# tag (vX.Y.Z), and publish -- that `release: published` event is what
+# publish.yml uses to build and upload to PyPI. See CONTRIBUTING.md.
+
+name-template: 'v$RESOLVED_VERSION'
+tag-template: 'v$RESOLVED_VERSION'
+template: |
+  $CHANGES
+
+categories:
+  - title: '🐛 Fixes'
+    labels:
+      - bug
+  - title: '✨ Features'
+    labels:
+      - enhancement
+  - title: '📚 Documentation'
+    labels:
+      - documentation
+  - title: '🧹 Maintenance'
+    labels:
+      - chore
+      - dependencies
+
+change-template: '- $TITLE @$AUTHOR (#$NUMBER)'
+change-title-escapes: '\<*_&'
+
+# We tag manually, so don't try to auto-bump versions based on labels.
+# Leave $RESOLVED_VERSION as a placeholder the maintainer overrides at
+# release time.
+version-resolver:
+  default: patch
+
+exclude-labels:
+  - skip-changelog

nvda_addon_testkit-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,74 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+      - run: 'pip install --only-binary :all: ruff'
+      - run: ruff check .
+      - run: ruff format --check .
+
+  unit:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-2025]
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+      - run: 'pip install --only-binary :all: -e ".[dev]"'
+      - run: python tools/build_spy.py
+      # Bare `pytest` so testpaths picks up tests_spy/ too. An explicit
+      # `pytest tests/` silently skips every spy test in CI.
+      - run: pytest -v
+
+  e2e:
+    runs-on: windows-2025
+    strategy:
+      fail-fast: false
+      matrix:
+        channel: [stable, alpha]
+    continue-on-error: ${{ matrix.channel == 'alpha' }}
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+      - run: pip install -e ".[dev]"
+      - run: python tools/build_spy.py
+      - name: Cache NVDA launchers
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/nvda-testkit
+          key: nvda-launcher-${{ matrix.channel }}-${{ github.run_id }}
+          restore-keys: nvda-launcher-${{ matrix.channel }}-
+      - run: nvda-testkit doctor
+      - run: pytest tests_e2e/ -v --nvda-channel=${{ matrix.channel }}
+      - if: failure()
+        uses: actions/upload-artifact@v5
+        with:
+          name: e2e-${{ matrix.channel }}-artifacts
+          path: testOutput/
+          if-no-files-found: warn

nvda_addon_testkit-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,40 @@
+name: Publish
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          persist-credentials: false
+          fetch-depth: 0
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+      - run: "pip install --only-binary :all: build twine"
+      - run: python -m build
+      - run: twine check dist/*
+      - uses: actions/upload-artifact@v5
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v6
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

nvda_addon_testkit-0.1.0/.github/workflows/release-drafter.yml

@@ -0,0 +1,23 @@
+name: Release Drafter
+
+on:
+  push:
+    branches:
+      - main
+  # Re-run when a PR is opened/edited so label changes are reflected without
+  # waiting for the next merge.
+  pull_request:
+    types: [opened, reopened, synchronize, edited, labeled, unlabeled]
+
+jobs:
+  update_release_draft:
+    permissions:
+      contents: write
+      pull-requests: write
+    runs-on: ubuntu-latest
+    steps:
+      - uses: release-drafter/release-drafter@6a93d829887aa2e0748befe2e808c66c0ec6e4c7 # v6.4.0
+        with:
+          config-name: release-drafter.yml
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

nvda_addon_testkit-0.1.0/.github/workflows/sonar.yml

@@ -0,0 +1,98 @@
+name: Sonar
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+# SonarCloud keeps whichever report finishes processing last, not the newest
+# commit, so overlapping scans can leave main showing an older analysis.
+concurrency:
+  group: sonar-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  # windows_only-marked tests only run on Windows, so a ubuntu-only coverage
+  # run would show them as permanently uncovered. This job measures that leg
+  # and hands the raw data to the scan job to merge.
+  windows_coverage:
+    name: Windows coverage
+    runs-on: windows-2025
+    permissions:
+      contents: read
+    # Matches the scan job's guard: nothing consumes this artifact on fork PRs.
+    if: github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository
+
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          persist-credentials: false
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+
+      - run: 'pip install --only-binary :all: -e ".[dev]"'
+      - run: python tools/build_spy.py
+
+      - name: Run tests with coverage
+        env:
+          COVERAGE_FILE: .coverage.windows.tests
+        # `coverage run -m pytest`, not `pytest --cov`: this package registers
+        # itself as a pytest11 entry-point plugin, so pytest's own plugin
+        # loader imports nvda_testkit's modules before pytest-cov's --cov
+        # flag would start tracing, permanently miscounting every top-level
+        # def/class line in them as uncovered.
+        run: coverage run -m pytest -v
+
+      - uses: actions/upload-artifact@v5
+        with:
+          name: windows-coverage-data
+          path: .coverage.windows.*
+          include-hidden-files: true # coverage data files start with a dot
+          retention-days: 1
+
+  sonar:
+    name: Sonar
+    runs-on: ubuntu-latest
+    needs: ["windows_coverage"]
+    permissions:
+      contents: read
+    # Fork PRs are never given repository secrets, so SONAR_TOKEN would be
+    # empty and the scan would fail with a red X the contributor can't clear.
+    if: github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository
+    env:
+      SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
+
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          fetch-depth: 0 # Sonar needs full history for new-code detection and blame
+          persist-credentials: false
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+
+      - run: 'pip install --only-binary :all: -e ".[dev]"'
+      - run: python tools/build_spy.py
+
+      - name: Run tests with coverage
+        run: coverage run -m pytest -v
+
+      # After the run above, never before: `coverage run` erases any
+      # .coverage.* data files already sitting in the workspace.
+      - name: Download the Windows leg's coverage
+        uses: actions/download-artifact@v6
+        with:
+          name: windows-coverage-data
+
+      - name: Merge into one coverage report
+        run: |
+          python -m coverage combine --append
+          python -m coverage xml
+
+      - name: SonarQube scan
+        if: env.SONAR_TOKEN != ''
+        uses: SonarSource/sonarqube-scan-action@22918119ff8e1ca75a623e15c8296b6ea4fbe28f # v8.2.1

nvda_addon_testkit-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.pyc
+.venv/
+dist/
+build/
+*.egg-info/
+testOutput/
+src/nvda_testkit/_spy/
+src/nvda_testkit/_version.py
+examples/demo-addon.nvda-addon
+.pytest_cache/
+.ruff_cache/
+.idea/

nvda_addon_testkit-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,64 @@
+# Contributing to nvda-addon-testkit
+
+Contributions are welcome — bug reports, feature suggestions, and PRs alike.
+
+## Reporting a bug
+
+Use the **Bug report** template at <https://github.com/ZirekHQ/nvda-addon-testkit/issues/new/choose>. It asks for the testkit version, NVDA channel, OS, and enough of a repro to run — fill in what you can, especially a minimal failing test or command.
+
+## Suggesting a feature
+
+Use the **Feature request** template. Describe the *problem* you're hitting, not just the API you imagine — that often surfaces a simpler fixture or a better name than the first idea.
+
+## Development setup
+
+```bash
+pip install -e ".[dev]"
+python tools/build_spy.py
+```
+
+`build_spy.py` packages `spy/` (the scriptable NVDA double) into the `.nvda-addon` the host-side tests install. Rerun it whenever you change anything under `spy/`.
+
+## Running tests
+
+```bash
+pytest                       # host and spy unit tests -- any platform
+pytest tests_e2e/ -v         # real NVDA -- Windows only
+nvda-testkit doctor          # check this machine
+```
+
+| Tree | Exercises | Runs on |
+| --- | --- | --- |
+| `tests/` | the host-side library, against `tests/fake_nvda.py` | Linux + Windows |
+| `tests_spy/` | `spy/`, the in-NVDA agent, against stubbed NVDA modules (`tests_spy/nvda_stubs.py`) | Linux + Windows |
+| `tests_e2e/` | both halves together, against a real provisioned NVDA | Windows only |
+
+`tests_e2e/` tests run serially — only one NVDA can own a desktop session, so `pytest-xdist` with more than one worker refuses to start rather than silently corrupting results.
+
+## Linting
+
+```bash
+ruff check .
+ruff format --check .
+```
+
+## Submitting a PR
+
+Use the pull request template. Link the issue with `Closes #N` in the PR body where one exists.
+
+- **Commit messages**: short imperative subject, optionally prefixed `fix:` / `feat:` / `ci:` / `chore:` / `docs:` when it clarifies the kind of change. Don't append the `(#NNNNN)` PR-number suffix — GitHub's squash-merge adds it automatically.
+- **Branch naming**: `<type>/<slug>`, e.g. `fix/rpc-race`, `feature/braille-namespace`.
+- **No `Co-Authored-By` trailers.**
+
+## Cutting a release
+
+Releases are tag-driven, not version-bumped by hand — `pyproject.toml` has no `version` field. The `hatch-vcs` build hook derives the package version from the git tag at build time.
+
+1. Publish a GitHub Release from `main` with a `vX.Y.Z` tag (semver; pre-1.0 minor bumps may break the fixture API).
+2. `.github/workflows/publish.yml` picks up the `release: published` event, builds the sdist/wheel, and uploads to PyPI via Trusted Publishing — no token to rotate.
+
+No separate changelog file to update — Release Drafter maintains a draft release from merged PR titles/labels as you go; open the draft, set the tag, and publish it to trigger the step above.
+
+### Why not fully automate this (conventional commits + semantic-release)?
+
+Considered and deliberately skipped. PRs are squash-merged, so main's history is already one commit per PR — parsing commit prefixes to categorize a release would just be a stricter, easier-to-typo restatement of what PR labels already give Release Drafter for free. More importantly, auto-bumping the version and auto-publishing on merge removes the last human checkpoint before something goes to PyPI, and pre-1.0 semver bumps (does this `feat:` deserve a minor, or does it actually break the fixture API?) are judgment calls a bot applies too mechanically at this stage. Worth revisiting if release volume ever makes the manual tag-and-publish step the actual bottleneck.