ci: add GitHub Actions workflow for unit tests

.github/workflows/ci.yml

@@ -0,0 +1,68 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+# Restrict the default GITHUB_TOKEN to read-only.
+# This workflow only checks out code and runs tests — no write access needed.
+# Satisfies OSSF Scorecard "Token-Permissions" check.
+permissions:
+  contents: read
+
+# Cancel any in-progress run for the same branch/PR when a new commit is pushed.
+# Prevents stacked runs from queuing up on active PR branches.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    # Matrix: Python 3.10–3.13 on Linux, plus a Windows smoke test on 3.13.
+    # The Windows leg specifically guards against platform-specific issues
+    # (UnicodeEncodeError on non-UTF-8 stdout, /bin/bash not found, etc.).
+    name: Python ${{ matrix.python-version }} / ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 10
+
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest]
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+        include:
+          - os: windows-latest
+            python-version: "3.13"
+
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
+        with:
+          python-version: ${{ matrix.python-version }}
+          # Caches the pip download cache keyed on pyproject.toml hash.
+          # Saves ~20 s per matrix leg on a warm cache.
+          cache: "pip"
+
+      - name: Install package and test dependencies
+        run: |
+          python -m pip install --upgrade pip setuptools wheel
+          pip install -e ".[dev]"
+
+      # Playwright browser binaries are intentionally NOT installed here.
+      # All 16 current unit tests are pure-Python and pass without a real browser:
+      # the `playwright` Python package is installed as a runtime dep (via pip install -e .)
+      # so `import playwright` works, but check_screenshot() gracefully returns
+      # (False, "unable to launch...") when no browser binary is present.
+      # Uncomment the step below when browser-level integration tests are added.
+      #
+      # - name: Install Playwright browsers
+      #   run: playwright install --with-deps chromium
+
+      - name: Run unit tests
+        run: pytest tests/unit/ -v --tb=short
+
+      # TODO: Add `ruff check src/ tests/` here once ruff is configured in pyproject.toml.

pyproject.toml

@@ -19,6 +19,9 @@ dependencies = [
     "platformdirs>=4.0",
 ]
 
+[project.optional-dependencies]
+dev = ["pytest>=7.4"]
+
 [project.scripts]
 webwright = "webwright.run.cli:app"