E2E foundation, contracts, and CI

.github/pull_request_template.md

@@ -0,0 +1,42 @@
+Title: E2E foundation, contracts, and CI
+
+Summary
+- Implements Playwright E2E scaffold with smoke + core flow specs (browse, scan)
+- Adds minimal API contracts for /api/scan, /api/scans/<id>/status, /api/directories
+- Aligns Dev CLI timestamps to timezone-aware ISO8601
+- Adds stable data-testid hooks to UI templates
+- Wires CI for pytest and strict E2E smoke
+- Updates docs/testing.md with quickstarts and CI notes
+
+Related
+- Story: story:e2e-testing
+- Phase: 02–03
+- Task(s):
+  - task:e2e:02-playwright-scaffold (Done)
+  - task:e2e:03-core-flows (partially addressed by initial specs; remaining flows in next branch)
+
+Local verification
+- Python tests: python -m pytest -q → green
+- Playwright E2E: npm install && npx playwright install --with-deps && npm run e2e → green
+
+CI
+- GitHub Actions workflow runs:
+  - Python tests (3.11)
+  - E2E smoke (Node 18) — strict, SCIDK_PROVIDERS=local_fs
+
+How to run locally
+- API contracts: python -m pytest tests/contracts/test_api_contracts.py -q
+- E2E: npm run e2e (uses e2e/global-setup.ts to boot the Flask server)
+
+Risk assessment
+- Low risk. Mostly additive tests/config/docs. UI changes limited to data-testid attributes.
+
+Merge checklist
+- [x] pytest green locally
+- [x] E2E green locally
+- [x] CI expected to pass (strict E2E)
+- [x] task:e2e:02-playwright-scaffold marked Done with completed_at
+- [ ] Reviewer sanity pass on docs/testing.md and CI workflow
+
+Post-merge (follow-up branch)
+- Expand Phase 03 core flows E2E and refine contracts as needed.

.github/workflows/ci.yml

@@ -0,0 +1,63 @@
+name: Tests
+
+on:
+  push:
+    branches: [ main, develop, release/** ]
+  pull_request:
+
+jobs:
+  python-tests:
+    name: Python tests (pytest)
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Upgrade pip and install Python deps
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e .[dev]
+      - name: Run pytest (exclude E2E)
+        run: |
+          python -m pytest -q -m "not e2e"
+
+  e2e:
+    name: E2E smoke (Playwright)
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Set up Python (for Flask app)
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Upgrade pip and install Python deps
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e .[dev]
+      - name: Set up Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 18
+          cache: 'npm'
+      - name: Install npm deps
+        run: npm ci
+      - name: Install Playwright browsers (with system deps)
+        run: npx playwright install --with-deps
+      - name: Run Playwright E2E
+        env:
+          # Keep E2E self-contained by only enabling local_fs provider
+          SCIDK_PROVIDERS: local_fs
+        run: npm run e2e
+      - name: Upload Playwright report (on failure)
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: playwright-report
+          path: |
+            playwright-report/
+            test-results/
+          if-no-files-found: ignore

README.md

@@ -11,9 +11,18 @@ python3 -m venv .venv
 source .venv/bin/activate
 # fish:
 source .venv/bin/activate.fish
-pip install -r requirements.txt
+
+# Recommended: install the package in editable mode
+pip install -e .            # runtime deps only
+# or for development (tests, Playwright helpers, etc.)
+pip install -e .[dev]
+# alternatively, use the provided requirements files:
+#   pip install -r requirements.txt         # runtime-only
+#   pip install -r requirements-dev.txt     # dev extras (editable)
 ```
 
+Note: do NOT run `pip install -r pyproject.toml`. pyproject.toml is not a requirements file; it is a build/metadata file. Use one of the commands above instead.
+
 2) Initialize environment variables (recommended):
 - bash/zsh:
 ```
@@ -167,16 +176,18 @@ Rclone provider (optional):
 ## Testing
 We use pytest for unit and API tests.
 
-Pytest is included in requirements.txt; after installing dependencies, run:
+Quick start:
 ```
 python3 -m pytest -q
 ```
 Notes:
 - If your shell doesn't expose a global `pytest` command (common in fish), using `python3 -m pytest` is the most reliable.
 - You can still run `pytest -q` if your PATH includes the virtualenv's bin directory.
 
-Conventions:
-- Tests live in tests/ and rely on pytest fixtures in tests/conftest.py (e.g., Flask app and client).
+Details:
+- Full testing overview: docs/testing.md (tools, fixtures, mocking strategy, env vars, and how to run subsets)
+- Pytest configuration lives in pyproject.toml (testpaths=tests, addopts=-q)
+- Tests live in tests/ and rely on pytest fixtures in tests/conftest.py (e.g., Flask app and client)
 - Add tests alongside new features in future cycles; see dev/cycles.md for cycle protocol.
 
 ## Notes