Add Playwright e2e tests for WebSocket and API integration

[JohnRDOrazio]

Summary

All existing tests (756 files) rely on mocked dependencies — fetch is stubbed, WebSocket is replaced with MockWebSocket, and contexts are provided via test wrappers. We need end-to-end tests that exercise the full stack against a real running backend to catch integration failures, WebSocket lifecycle issues, and real auth flows.

Plan

A detailed plan has been committed to dev at docs/plans/e2e-testing.md. It covers:

Test categories

• API integration tests — Playwright APIRequestContext hitting the real backend (project CRUD, ontology ops, branches, PRs, lint, search)
• WebSocket tests — raw ws connections for protocol-level testing + browser-based WebSocket interception for collab and index-status endpoints
• UI workflow tests — full browser journeys (auth, ontology editing, branch+PR workflow, health check)

Implementation phases

1. Foundation — Install Playwright, auth fixtures, API integration tests, CI docker-compose
2. WebSocket tests — collab handshake, presence, index-status WS, reconnection
3. UI workflow tests — auth flow, project management, ontology editing, branch+PR
4. CI hardening — multi-browser matrix, flaky test detection, trace artifacts

Open questions

• Auth strategy for CI (service account vs test bypass header)
• Test database seeding (Alembic + SQL fixtures vs API calls)
• Scope boundary (ontokit-web vs monorepo-level e2e/ directory)
• MinIO requirement for initial phases

References

• Plan document: docs/plans/e2e-testing.md on dev

[m13v]

the phased approach makes sense but the open question about auth strategy for CI is the one to solve first since everything downstream depends on it. for WebSocket tests specifically, a service account with a long-lived token is better than a test bypass header because the bypass header means you are testing a different code path than production, which defeats the purpose of E2E. for the collab WebSocket tests (handshake, presence, reconnection), open two parallel browser contexts (not pages, contexts) so each has its own WebSocket connection. the tricky part is reconnection testing. do not just disconnect the network and hope. use page.route to intercept the WebSocket upgrade request and abort it, then verify the client retries. for the test database seeding, API calls over Alembic fixtures since fixtures go stale when the schema changes and nobody remembers to update them. the API seeding approach means your test data is always consistent with the current schema.

[m13v]

we built an open source framework that handles browser context isolation and auth state management for Playwright E2E suites. the browser session management that keeps parallel test contexts independent: https://github.com/assrt-ai/assrt-freestyle/blob/main/src/core/browser.ts

[JohnRDOrazio]

a service account with a long-lived token is better than a test bypass header

I completely agree. Claude Code started cooking up the plan, and mentioned the bypass header as a second possibility, but I prefer to test things using the same code path. So when it comes time to implement the e2e testing I'll push in that direction.

for the test database seeding, API calls over Alembic fixtures

I completely agree here too, it's better to test with real data to avoid code drift.

we built an open source framework that handles browser context isolation and auth state management for Playwright E2E suites. the browser session management that keeps parallel test contexts independent: https://github.com/assrt-ai/assrt-freestyle/blob/main/src/core/browser.ts

Sounds like a very useful tool, but I think the repo is private? In the https://github.com/assrt-ai organization I only see the assrt-mcp repo, so assrt-freestyle seems to be a private repo.

In any case when the time comes to implement this, if you would like to contribute that would be great. I'm thinking of holding off on the e2e tests until the project is a little more stable, but once they are in place it will help further development to keep things in line and avoid decoupling of the frontend and the backend.