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

nvda_addon_testkit-0.1.3/.github/CODEOWNERS

@@ -0,0 +1 @@
+* @ZirekHQ/maintainers

{nvda_addon_testkit-0.1.0 → nvda_addon_testkit-0.1.3/.github}/CONTRIBUTING.md

@@ -54,11 +54,11 @@ Use the pull request template. Link the issue with `Closes #N` in the PR body wh
 
 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.
+1. Run `prepare-release.yml` (Actions tab → **Prepare release** → Run workflow). Leave `new_tag` blank to let it compute the next version from Conventional Commit subjects since the last tag (`scripts/next-version.sh`); pass a `vX.Y.Z` value there instead to override it. Check `dry_run` to only see the computed version without tagging or publishing anything.
+2. The `release` environment gate requires a maintainer approval before anything happens — that's the human checkpoint, not the version computation.
+3. Once approved, `prepare-release.yml`'s `tag-and-release` job tags `main` at the resolved commit, force-moves the `v<major>` tag consumers pin (README and GitHub Marketplace listings use `@v1`), and publishes the GitHub Release with auto-generated notes.
+4. That tag feeds `publish-python.yml`, which builds the sdist/wheel and uploads to PyPI via Trusted Publishing — no token to rotate.
 
 ### 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.
+The version bump itself *is* automated — computed from commit prefixes since the last tag. What's deliberately kept manual is the human approval gate before anything tags or publishes: pre-1.0 semver bumps (does this `feat:` deserve a minor, or does it actually break the fixture API?) are judgment calls worth a maintainer's eyes before they go to PyPI and the Marketplace. Worth revisiting if release volume ever makes that approval step the actual bottleneck.

nvda_addon_testkit-0.1.3/.github/workflows/CI.yml

@@ -0,0 +1,98 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
+        with:
+          python-version: "3.13"
+      - run: 'pip install --only-binary :all: ruff'
+      - run: ruff check .
+      - run: ruff format --check .
+
+  dependency-audit:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
+        with:
+          python-version: "3.13"
+      - run: 'pip install --only-binary :all: -e ".[dev]"'
+      - run: 'pip install --only-binary :all: pip-audit'
+      - run: pip-audit
+
+  unit:
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 15
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-2025]
+    steps:
+      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # 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: ${{ matrix.os }}
+    timeout-minutes: 30
+    strategy:
+      fail-fast: false
+      matrix:
+        # windows-2022 covers Windows 10 22H2 (ESU). Drop it once ESU
+        # coverage is no longer needed.
+        os: [windows-2025, windows-2022]
+        channel: [stable, alpha]
+    continue-on-error: ${{ matrix.channel == 'alpha' }}
+    steps:
+      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
+        with:
+          python-version: "3.13"
+      - run: 'pip install --only-binary :all: -e ".[dev]"'
+      - run: python tools/build_spy.py
+      - name: Cache NVDA launchers
+        uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4
+        with:
+          path: ~/.cache/nvda-testkit
+          key: nvda-launcher-${{ matrix.os }}-${{ matrix.channel }}-${{ github.run_id }}
+          restore-keys: nvda-launcher-${{ matrix.os }}-${{ matrix.channel }}-
+      - run: nvda-testkit doctor
+      - run: pytest tests_e2e/ -v --nvda-channel=${{ matrix.channel }}
+      - if: failure()
+        uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5
+        with:
+          name: e2e-${{ matrix.os }}-${{ matrix.channel }}-artifacts
+          path: testOutput/
+          if-no-files-found: warn

nvda_addon_testkit-0.1.3/.github/workflows/notify-docs.yml

@@ -0,0 +1,52 @@
+name: Notify docs site
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      ref:
+        description: Ref or tag to notify about (defaults to the current ref)
+        required: false
+        type: string
+
+permissions:
+  contents: read
+
+jobs:
+  dispatch:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - name: Resolve ref
+        id: resolve
+        env:
+          EVENT_NAME: ${{ github.event_name }}
+          RELEASE_TAG: ${{ github.event.release.tag_name }}
+          INPUT_REF: ${{ inputs.ref }}
+          DEFAULT_REF: ${{ github.ref_name }}
+        run: |
+          if [ "$EVENT_NAME" = "release" ]; then
+            ref="$RELEASE_TAG"
+          else
+            ref="${INPUT_REF:-$DEFAULT_REF}"
+          fi
+          if ! git check-ref-format --branch "$ref" >/dev/null 2>&1 \
+             && ! git check-ref-format "refs/tags/$ref" >/dev/null 2>&1; then
+            echo "Invalid ref: $ref" >&2
+            exit 1
+          fi
+          echo "ref=$ref" >> "$GITHUB_OUTPUT"
+
+      - name: Dispatch update to docs site
+        uses: peter-evans/repository-dispatch@ff45666b9427631e3450c54a1bcbee4d9ff4d7c0 # v3
+        with:
+          token: ${{ secrets.DOCS_DISPATCH_TOKEN }}
+          repository: ZirekHQ/ZirekHQ.github.io
+          event-type: update-docs
+          client-payload: |-
+            {
+              "repository": ${{ toJSON(github.repository) }},
+              "ref": ${{ toJSON(steps.resolve.outputs.ref) }},
+              "actor": ${{ toJSON(github.actor) }}
+            }

nvda_addon_testkit-0.1.3/.github/workflows/prepare-release.yml

@@ -0,0 +1,154 @@
+name: Prepare release
+
+# The single dispatch surface for cutting a release. hatch-vcs derives the version from the
+# git tag (pyproject.toml), so there's no version file to bump or PR to open first -- the
+# environment:release approval gate below is the human checkpoint instead.
+#
+# tag-and-release and pypi live here rather than in a separate workflow_call file: PyPI's
+# trusted-publisher attestation check verifies the Build Config URI against the *root*
+# dispatched workflow, not the immediate caller, so a second layer of workflow_call between
+# this dispatch and publish-python.yml breaks it (confirmed by three failed release runs
+# where the Build Config URI reported the wrong workflow entirely).
+on:
+  workflow_dispatch:
+    inputs:
+      new_tag:
+        description: "Override the vX.Y.Z tag"
+        required: false
+        type: string
+      dry_run:
+        description: "Dry Run: compute the version, tag nothing, publish nothing"
+        required: false
+        type: boolean
+        default: false
+
+permissions: {}
+
+jobs:
+  compute-version:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: read
+    outputs:
+      version: ${{ steps.next.outputs.version }}
+      sha: ${{ steps.resolve-sha.outputs.sha }}
+    steps:
+      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5
+        with:
+          ref: main
+          fetch-depth: 0
+          persist-credentials: false
+
+      # Exported so tag-and-release tags/checks-out this exact commit rather than the dispatch's
+      # own github.sha -- main can move during approve's wait, and this checkout is the only
+      # thing pinning which commit the computed version actually describes.
+      - name: Resolve commit SHA
+        id: resolve-sha
+        run: echo "sha=$(git rev-parse HEAD)" >> "$GITHUB_OUTPUT"
+
+      - name: Compute next version
+        id: next
+        env:
+          NEW_TAG: ${{ inputs.new_tag }}
+        run: |
+          set -euo pipefail
+          if [ -n "${NEW_TAG:-}" ]; then
+            version="${NEW_TAG#v}"
+            if ! echo "$version" | grep -qE '^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$'; then
+              echo "::error::new_tag '${NEW_TAG}' doesn't look like a vX.Y.Z tag" >&2
+              exit 1
+            fi
+          else
+            version="$(bash scripts/next-version.sh)"
+          fi
+          echo "version=${version}" >> "$GITHUB_OUTPUT"
+          echo "Computed v${version}"
+
+  approve:
+    name: Approve release
+    needs: compute-version
+    if: inputs.dry_run != true && github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    environment: release
+    permissions: {}
+    steps:
+      - env:
+          VERSION: ${{ needs.compute-version.outputs.version }}
+        run: echo "Approved v${VERSION} for release"
+
+  tag-and-release:
+    needs: [compute-version, approve]
+    if: always() && needs.compute-version.result == 'success' && needs.approve.result == 'success'
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: write
+    env:
+      VERSION: ${{ needs.compute-version.outputs.version }}
+      SHA: ${{ needs.compute-version.outputs.sha }}
+      GH_TOKEN: ${{ github.token }}
+    steps:
+      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5
+        with:
+          ref: ${{ needs.compute-version.outputs.sha }}
+          persist-credentials: true
+
+      - name: Push release tag
+        # Checked against origin (shallow fetch), not the local clone. An annotated tag peels to
+        # the commit SHA via a separate `^{}`-suffixed query -- ls-remote only returns that line
+        # when asked for it by name, so one unsuffixed query can't tell the two cases apart.
+        run: |
+          set -euo pipefail
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          existing="$(git ls-remote origin "refs/tags/v${VERSION}^{}" | cut -f1)"
+          if [ -z "$existing" ]; then
+            existing="$(git ls-remote origin "refs/tags/v${VERSION}" | cut -f1)"
+          fi
+          if [ -n "$existing" ]; then
+            if [ "$existing" != "$SHA" ]; then
+              echo "::error::v${VERSION} already exists on origin and points at ${existing}, not this commit (${SHA})" >&2
+              exit 1
+            fi
+            echo "v${VERSION} already exists on origin and points at this commit -- reusing it"
+          elif [ "$GITHUB_REF" = "refs/heads/main" ]; then
+            git tag "v${VERSION}"
+            git push origin "v${VERSION}"
+          else
+            echo "::error::Refusing to create v${VERSION} from ${GITHUB_REF} -- release tags are only created from main" >&2
+            exit 1
+          fi
+
+      # README documents `uses: zirekhq/nvda-addon-testkit@v1`, and GitHub Marketplace
+      # consumers pin the same tag -- this step keeps it on the latest release in its major line.
+      - name: Move major version tag
+        run: |
+          set -euo pipefail
+          major="v${VERSION%%.*}"
+          git tag -fa "$major" -m "$major" "$SHA"
+          git push origin "$major" --force
+
+      - name: Publish GitHub Release
+        # Replaces the release-drafter draft this step used to patch to non-draft --
+        # --generate-notes computes the same changelog from merged PRs on demand instead.
+        run: |
+          set -euo pipefail
+          if ! gh release view "v${VERSION}" --repo "${GITHUB_REPOSITORY}" >/dev/null 2>&1; then
+            gh release create "v${VERSION}" \
+              --repo "${GITHUB_REPOSITORY}" \
+              --target "${SHA}" \
+              --title "v${VERSION}" \
+              --generate-notes
+          fi
+
+  pypi:
+    name: PyPI
+    needs: [compute-version, tag-and-release]
+    permissions:
+      contents: read
+      id-token: write
+    uses: ./.github/workflows/publish-python.yml # zizmor: ignore[self-repository] low-severity style suggestion (use '$/...'), not a finding -- zizmor.yml doesn't pin a CLI version to confirm '$/' support
+    with:
+      ref: v${{ needs.compute-version.outputs.version }}

nvda_addon_testkit-0.1.3/.github/workflows/project-sync.yml

@@ -0,0 +1,15 @@
+name: Project sync
+
+on:
+  issues:
+    types: [opened, assigned]
+  pull_request:
+    types: [opened]
+
+permissions: {}
+
+jobs:
+  sync:
+    uses: ZirekHQ/.github/.github/workflows/project-sync.yml@54452127e2c87f8ecfe358fc88e0f1fe411859b3 # main
+    secrets:
+      PROJECT_SYNC_TOKEN: ${{ secrets.PROJECT_SYNC_TOKEN }}

nvda_addon_testkit-0.1.3/.github/workflows/publish-python.yml

@@ -0,0 +1,85 @@
+name: Publish Python
+
+on:
+  release:
+    types: [published]
+  # Manual retry path (e.g. PyPI publish failed after the GitHub release already went out).
+  workflow_dispatch: {}
+  workflow_call:
+    inputs:
+      ref:
+        description: "Exact commit or tag to build and publish"
+        required: true
+        type: string
+
+permissions: {}
+
+jobs:
+  # github.event_name mirrors the CALLING workflow's trigger through a workflow_call
+  # (prepare-release.yml's dispatch shows up as 'workflow_dispatch' here too) -- workflow_ref
+  # stays bound to the top-level caller, so this checks that, not event_name alone.
+  gate:
+    if: >-
+      github.event_name == 'workflow_dispatch' &&
+      startsWith(github.workflow_ref, format('{0}/.github/workflows/publish-python.yml@', github.repository))
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    environment: release
+    permissions: {}
+    steps:
+      - run: echo "approved"
+
+  build:
+    needs: gate
+    if: always() && (needs.gate.result == 'success' || needs.gate.result == 'skipped')
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5
+        with:
+          ref: ${{ inputs.ref || github.sha }}
+          persist-credentials: false
+          fetch-depth: 0
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
+        with:
+          python-version: "3.13"
+      - run: "pip install --only-binary :all: build twine"
+      # Without this, hatchling's `artifacts = ["src/nvda_testkit/_spy/*.nvda-addon"]`
+      # matches nothing -- the bundle is gitignored and only exists once built --
+      # so the published wheel silently ships without it and every real (non-fake)
+      # provision() fails require_spy_bundle().
+      - run: python tools/build_spy.py
+      - run: python -m build
+      - run: twine check dist/*
+      - uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    # Without this, publish silently no-ops on the release.yml call path: its default
+    # success() check walks the whole ancestor chain, and gate (an ancestor via build)
+    # is legitimately skipped there, not succeeded.
+    if: always() && needs.build.result == 'success'
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@018cc2cf5baa6db3ef3c5f8a56943fffe632ef53 # v6
+        with:
+          name: dist
+          path: dist/
+      # pypa publishes security fixes to this branch without re-tagging v1, so
+      # pinning trades that auto-patching for the blanket pinning policy --
+      # bump this SHA by hand if pypa/gh-action-pypi-publish ships a fix.
+      - uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # release/v1
+        with:
+          # PyPI doesn't support reusable workflows as a Trusted Publisher (pypi/warehouse#11096):
+          # this job runs via workflow_call from prepare-release.yml, so the attestation's Build
+          # Config URI is the caller, not this file, and PyPI rejects it. Drop once that's fixed.
+          attestations: false

nvda_addon_testkit-0.1.3/.github/workflows/sonar-fork-coverage.yml

@@ -0,0 +1,120 @@
+name: Sonar fork coverage
+
+# The Sonar job in sonar.yml is deliberately skipped for fork PRs because
+# forks are never given SONAR_TOKEN. This workflow builds what a real scan
+# needs -- a full checkout (including git history, for Sonar's blame/new-code
+# detection) plus a coverage report -- using only the read-only, secret-less
+# token that `pull_request` gets for fork PRs, and packages it as a plain tar
+# archive artifact.
+#
+# sonar-fork-scan.yml (triggered by a maintainer commenting `/sonar` on the
+# PR after reviewing the diff) extracts that archive with plain `tar`, never a
+# git operation, so it never runs git fetch/checkout against fork content and
+# never executes anything from the fork -- the archive is only read
+# statically by the Sonar scanner. This workflow must never gain
+# `secrets:` access and must never do anything beyond running the PR's own
+# test suite, exactly as any other fork `pull_request` job already safely
+# does.
+
+on:
+  pull_request:
+    branches: [main]
+
+permissions: {}
+
+concurrency:
+  group: sonar-fork-coverage-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
+jobs:
+  # Mirrors sonar.yml's windows_coverage job: windows_only-marked tests only
+  # run on Windows, so without this leg they'd land in the fork's report as
+  # permanently uncovered.
+  windows_coverage:
+    name: Windows coverage for fork scan
+    runs-on: windows-2025
+    timeout-minutes: 20
+    permissions:
+      contents: read
+    if: github.event.pull_request.head.repo.full_name != github.repository
+    steps:
+      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5
+        with:
+          ref: ${{ github.event.pull_request.head.sha }}
+          persist-credentials: false
+
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # 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. Mirrors sonar.yml.
+        run: coverage run -m pytest -v
+
+      - uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5
+        with:
+          name: sonar-fork-windows-coverage
+          path: .coverage.windows.*
+          include-hidden-files: true # coverage data files start with a dot
+          retention-days: 7
+
+  coverage:
+    name: Build coverage for fork scan
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    needs: ["windows_coverage"]
+    permissions:
+      contents: read
+    # Same-repo PRs are scanned directly by sonar.yml; only forks need this.
+    if: github.event.pull_request.head.repo.full_name != github.repository
+    steps:
+      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5
+        with:
+          # Pinned to the actual PR head, not actions/checkout's default
+          # ephemeral merge commit -- otherwise the scanner analyzes a
+          # commit SHA that doesn't match the PR, and SonarCloud can't
+          # attach its status to the commit branch protection actually
+          # checks.
+          ref: ${{ github.event.pull_request.head.sha }}
+          fetch-depth: 0 # Sonar needs full history for new-code detection and blame
+          persist-credentials: false
+
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # 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@018cc2cf5baa6db3ef3c5f8a56943fffe632ef53 # v6
+        with:
+          name: sonar-fork-windows-coverage
+
+      - name: Merge into one coverage report
+        run: |
+          python -m coverage combine --append
+          python -m coverage xml
+
+      - name: Archive workspace for the manual scan workflow
+        run: tar -czf "$RUNNER_TEMP/workspace.tar.gz" -C "$GITHUB_WORKSPACE" .
+
+      - uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5
+        with:
+          name: sonar-fork-workspace
+          path: ${{ runner.temp }}/workspace.tar.gz
+          retention-days: 7