E2E foundation complete: Playwright scaffold + core flow specs, API contracts, CI tighten, docs

- Add Playwright config/global setup already in repo; add browse.spec.ts and scan.spec.ts specs using stable data-testid hooks
- Fix scan E2E assertions to avoid regex pitfalls and allow multiple occurrences
- Add API contracts for /api/scan, /api/scans/<id>/status, /api/directories
- Make E2E job strict in CI; document in docs/testing.md and add PR template
- Align Dev CLI timestamps and finalize task:e2e:02-playwright-scaffold bookkeeping

Author: patchmemory

.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.

docs/testing.md

@@ -200,7 +200,31 @@ CI (phase 05)
   - Python tests (pytest): sets up Python 3.11, installs deps (requirements.txt / pyproject), runs python -m pytest -q
   - E2E smoke (Playwright): sets up Node 18, installs deps, installs browsers with npx playwright install --with-deps, runs npm run e2e
 - Environment: SCIDK_PROVIDERS=local_fs is used during E2E to avoid external dependencies.
-- Continue-on-error: E2E job is marked continue-on-error: true during bring-up; tighten later when stable.
+- E2E job is strict (no continue-on-error) now that smoke and core flows are stable; monitor the first PR run and investigate any flakes.
 - To run the same locally:
   - python -m pytest -q
   - npm install && npx playwright install --with-deps && npm run e2e
+
+
+
+Updates (Phase 03 prep)
+- New API contracts added under tests/contracts/test_api_contracts.py:
+  - test_scan_contract_local_fs: POST /api/scan returns a payload with an id or ok.
+  - test_scan_status_contract: GET /api/scans/<id>/status returns a dict with a status/state/done field.
+  - test_directories_contract: GET /api/directories returns a list with items containing path.
+- New Playwright specs:
+  - e2e/browse.spec.ts: navigates to Files and verifies stable hooks, no console errors.
+  - e2e/scan.spec.ts: posts /api/scan for a temp directory and verifies the Home page lists it.
+
+How to run the new tests
+- Contracts subset:
+  - python -m pytest tests/contracts/test_api_contracts.py::test_scan_contract_local_fs -q
+  - python -m pytest tests/contracts/test_api_contracts.py::test_scan_status_contract -q
+  - python -m pytest tests/contracts/test_api_contracts.py::test_directories_contract -q
+- E2E specs:
+  - npm run e2e                # runs all specs including smoke, browse, scan
+  - npm run e2e:headed         # optional, debug mode
+
+Notes
+- E2E relies on BASE_URL from global-setup (spawns Flask). SCIDK_PROVIDERS defaults to local_fs in CI.
+- The scan E2E uses a real temp directory under the runner OS temp path and triggers a synchronous scan via /api/scan.

e2e/browse.spec.ts

@@ -0,0 +1,25 @@
+import { test, expect } from '@playwright/test';
+
+// Browse flow: navigate to Files and ensure stable hooks are present and no console errors
+
+test('files page loads and shows stable hooks', async ({ page, baseURL }) => {
+  const consoleMessages: { type: string; text: string }[] = [];
+  page.on('console', (msg) => {
+    consoleMessages.push({ type: msg.type(), text: msg.text() });
+  });
+
+  const url = baseURL || process.env.BASE_URL || 'http://127.0.0.1:5000';
+  await page.goto(url);
+
+  // Go to Files via stable nav hook
+  await page.getByTestId('nav-files').click();
+
+  // Expect the Files page to render
+  await expect(page.getByTestId('files-title')).toBeVisible();
+  await expect(page.getByTestId('files-root')).toBeVisible();
+
+  // Let network settle and ensure no console errors
+  await page.waitForLoadState('networkidle');
+  const errors = consoleMessages.filter((m) => m.type === 'error');
+  expect(errors.length).toBe(0);
+});

e2e/scan.spec.ts

@@ -0,0 +1,36 @@
+import { test, expect, request } from '@playwright/test';
+import os from 'os';
+import fs from 'fs';
+import path from 'path';
+
+// Scan flow: create a small temp directory on the runner, POST /api/scan to index it,
+// then verify Home lists it under Scanned Sources.
+
+function makeTempDirWithFile(prefix = 'scidk-e2e-'): string {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), prefix));
+  fs.writeFileSync(path.join(dir, 'e2e.txt'), 'hello');
+  return dir;
+}
+
+test('scan a temp directory and verify it appears on Home', async ({ page, baseURL, request: pageRequest }) => {
+  const base = baseURL || process.env.BASE_URL || 'http://127.0.0.1:5000';
+  const tempDir = makeTempDirWithFile();
+
+  // Kick off a non-recursive scan via HTTP API (synchronous in current implementation)
+  const api = pageRequest || (await request.newContext());
+  const resp = await api.post(`${base}/api/scan`, {
+    headers: { 'Content-Type': 'application/json' },
+    data: { path: tempDir, recursive: false },
+  });
+  expect(resp.ok()).toBeTruthy();
+
+  // Navigate to Home and check that the scanned source is listed
+  await page.goto(base);
+  await page.waitForLoadState('domcontentloaded');
+  await page.waitForLoadState('networkidle');
+
+  // The Home page shows a Scanned Sources list when directories exist.
+  // Assert the tempDir path appears somewhere in the page. Use getByText to avoid regex parsing of slashes.
+  const occurrences = await page.getByText(tempDir, { exact: false }).count();
+  expect(occurrences).toBeGreaterThan(0);
+});

tests/contracts/test_api_contracts.py

@@ -33,3 +33,60 @@ def test_browse_contract_local_fs_root_listing(client):
     for e in data['entries']:
         assert isinstance(e, dict)
         assert 'name' in e and 'type' in e
+
+
+
+def test_scan_contract_local_fs(client, tmp_path):
+    # Create a temporary file to ensure directory is non-empty
+    p = tmp_path / 'sample.txt'
+    p.write_text('hello', encoding='utf-8')
+    r = client.post('/api/scan', json={'path': str(tmp_path), 'recursive': False})
+    assert r.status_code == 200
+    data = r.get_json()
+    # legacy /api/scan may return a dict or minimal payload; accept either id or ok
+    assert isinstance(data, dict)
+    assert 'id' in data or 'ok' in data or 'scan_id' in data
+
+
+def test_scan_status_contract(client, tmp_path):
+    # kick off a small scan
+    (tmp_path / 'a.txt').write_text('x', encoding='utf-8')
+    r = client.post('/api/scan', json={'path': str(tmp_path), 'recursive': False})
+    assert r.status_code == 200
+    payload = r.get_json() or {}
+    scan_id = payload.get('id') or payload.get('scan_id') or payload.get('scanId')
+    # If synchronous legacy scan, status may be available via last item in /api/scans
+    if not scan_id:
+        scans_resp = client.get('/api/scans')
+        assert scans_resp.status_code == 200
+        scans = scans_resp.get_json() or []
+        assert isinstance(scans, list)
+        if scans:
+            scan_id = scans[-1].get('id')
+    # If still missing, skip to keep contract minimal/non-flaky
+    if not scan_id:
+        pytest.skip('scan_id not available from API after legacy /api/scan response')
+    st = client.get(f'/api/scans/{scan_id}/status')
+    assert st.status_code == 200
+    sd = st.get_json()
+    assert isinstance(sd, dict)
+    # Expect at least a status/state field
+    assert any(k in sd for k in ('status', 'state', 'done'))
+
+
+def test_directories_contract(client, tmp_path):
+    # Ensure at least one directory exists in the registry by running a quick scan
+    (tmp_path / 'b.txt').write_text('y', encoding='utf-8')
+    client.post('/api/scan', json={'path': str(tmp_path), 'recursive': False})
+    d = client.get('/api/directories')
+    assert d.status_code == 200
+    arr = d.get_json()
+    assert isinstance(arr, list)
+    # Minimal shape
+    if arr:
+        for item in arr:
+            assert isinstance(item, dict)
+            assert 'path' in item
+            # optional helpful fields
+            _ = item.get('scanned') if isinstance(item, dict) else None
+            _ = item.get('recursive') if isinstance(item, dict) else None