Testing and demos

Standard checks

Run all existing project checks with:

just test

This runs Go tests, Svelte/TypeScript diagnostics, frontend Vitest tests, a VitePress production build, and deployment helper checks. All production builds can be checked with:

just build

Backend tests

• internal/domain/room_test.go verifies vote secrecy, lifetime history, revision tracking, summary calculations, ties, and terminal session rules.
• internal/application/service_test.go verifies demo-team rounds plus persistence and locking of ended sessions.
• internal/adapters/httpapi/handler_test.go verifies focused handler behavior such as internal-error redaction and HTTP/WebSocket parity for ending a session.
• internal/adapters/httpapi/api_integration_test.go runs a complete room lifecycle over a real httptest HTTP server and verifies the public REST, SSE, and WebSocket contracts against migrated temporary SQLite.
• internal/adapters/eventstore/repository_contract_test.go runs the same append, conflict, history, replay, and rebuild contract against SQLite and, when configured, PostgreSQL.
• internal/database/migrations_test.go verifies fresh SQLite migration, repeated execution, legacy-schema adoption, and SQLite/PostgreSQL migration-file parity.
• internal/adapters/postgres/repository_test.go verifies PostgreSQL notifications and listener reconnection when TEST_DATABASE_URL is set.
• internal/adapters/webapp/handler_test.go verifies prerendered-page and dynamic-route fallback serving, backend delegation, asset caching, and missing-asset behavior.

Frontend tests

Vitest covers typed API error handling, room-session transitions and stale transport callbacks, optimistic-vote rollback, WebSocket closure and reconnection, and the pure poker-table layout functions. Run it directly with npm run test --prefix frontend.

GitLab CI supplies PostgreSQL 18 to the backend test job through TEST_DATABASE_URL. Run the integration test locally against a disposable database with:

cd backend
TEST_DATABASE_URL='postgres://poker:poker@localhost:5432/poker_test?sslmode=disable' go test ./...

CI also runs go test -race ./... to cover the application workers, realtime hub, and PostgreSQL listener under the race detector.

API smoke tests

The in-process API integration tests are part of every go test ./... run. A separate black-box smoke package uses only the public HTTP API and is skipped unless SMOKE_BASE_URL is set. Run it against an existing development server, container, worktree deployment, or remote environment with:

just api-smoke url=http://127.0.0.1:8080

The smoke test checks health, creates and retrieves a uniquely named room, votes without leaking the card before reveal, reveals the vote, and ends the session. The ended smoke-test room remains in the target database because the API has no room-deletion operation.

To build a backend binary, start it on loopback with disposable SQLite, wait for health, run the smoke package, and clean everything up automatically, use:

just api-smoke-local

Set SMOKE_PORT if port 18080 is already in use. GitLab runs this process-level smoke after the regular backend tests and vet checks, covering application startup, automatic migrations, middleware, routing, and persistence.

Documentation checks

The documentation has an isolated dependency lockfile. Validate it directly with:

npm ci --prefix docs
just docs-build

To verify the static runtime image, run just docs-container-build or start it at http://<branch>-docs.pointing.localhost with just docs-container-up.

Browser smoke test and Playwright demonstration

With the application running locally, install Chromium and run the assertion-based, two-user smoke test with:

just browser-smoke

Pass another local or remote application URL with just browser-smoke url=https://planning.example.com. The test creates a uniquely named room, joins from two isolated browser contexts, verifies live vote counts and hidden votes, reveals both estimates, and ends the session. The ended room remains in the target database because the application has no room-deletion operation. Set SMOKE_TIMEOUT to change the default 30-second Playwright timeout.

GitLab's browser-smoke job runs only in scheduled pipelines that define BROWSER_SMOKE_URL. Create a pipeline schedule on the default branch with cron 0 */6 * * *, select the desired timezone, and add the target URL as a protected CI/CD variable. Every run retains a downloadable host-browser recording as smoketest.webm for seven days; failed runs also include a screenshot.

Demo recording

The recorder has an isolated Node package under demo/. With the development servers running:

npm ci --prefix demo
npm exec --prefix demo -- playwright install chromium
npm run demo --prefix demo

demo/record.mjs drives this flow:

1. create a room;
2. change the topic;
3. add demonstration teammates;
4. cast the facilitator vote;
5. switch from SSE to WebSocket;
6. reveal votes;
7. start the next round.

The recording is written to demo/generated/backlog-holdem-demo.webm. The entire demo/generated/ directory is ignored so browser recordings and screenshots are never committed accidentally.

The demo is a repeatable walkthrough rather than a test; demo/smoketest.mjs provides the assertion-based multi-context coverage.

Container build checks

Run the dedicated aggregate test stage without producing a runtime image:

docker build -f deployment/Dockerfile --target test -t pointing:test .

A normal root Docker build also executes both the frontend-test and backend-test stages before producing the runtime image:

docker build -f deployment/Dockerfile -t pointing:local .

This complements, rather than replaces, the faster host-side just test checks.