E2E Test Contract
The Cypress suite is a reusable test contract for the frontend against a running backend. It verifies the critical OGRRE workflows without requiring backend source changes.
Covered workflows
The current suite covers:
- Core navigation from projects to record groups to records.
- Project and record group creation, editing, and cleanup.
- Record review actions, defective marking, and record-to-record navigation.
- Record notes creation, editing, and deletion.
- Team and scoped records table filtering.
- Upload validation, upload API calls, and export/download behavior.
- Schema field create, edit, and delete flows.
- Login redirects and permission-gated navigation/actions.
Seed data
Seed-dependent tests read expected names from cypress/fixtures/seeded-data.json. The default seed currently expects:
| Fixture key | Expected value |
|---|---|
projectName | ISGS Project |
recordGroupName | Precambrian_WellCompletion_1 |
recordName | 121190087702_WELL_COMPLETION_REPORT_1 |
nextRecordName | 120650345000_WELL_COMPLETION_REPORT_1 |
previousRecordName | 120272454800_WELL_COMPLETION_REPORT_1 |
reviewFieldName | Fractured |
filterRecordName | 120710031700_WELL_COMPLETION_REPORT_1 |
filterNextRecordName | 120973414200_WELL_COMPLETION_REPORT_2 |
recordGroupRecordCount | 17 |
When seed data changes, update the fixture in the same commit as the test adjustment. Prefer stable names over database ObjectIds so the suite can run against restored dumps, local Docker, or deployed test environments.
Test ownership
Tests that create data use test-owned names and clean up through backend APIs. Specs should not depend on execution order. Mutating specs should either restore seed data before they run or create their own isolated project and record group.
Use the shared Cypress helpers in cypress/support/commands.js for backend lookup, API cleanup, login setup, and seeded entity resolution.
Authentication modes
Configure auth with CYPRESS_AUTH_MODE:
| Mode | Use |
|---|---|
mock, stub, or stubbed | Stub /check_auth responses while running OGRRE workflows against the real backend. This is the default for local and CI E2E runs. |
disabled | Do not mock frontend auth. Use only when intentionally relying on the target backend's auth behavior. |
google | Legacy Google token login. Use only when intentionally testing a real auth-integrated environment. |
required | Auth-required API checks. Specs that need this mode skip unless it is explicitly set. |
Environment variables
Local npm scripts set E2E-safe defaults before launching Cypress. They read ports and collaborator values from deployment/.env.e2e or deployment/.env.e2e.example, then set the corresponding CYPRESS_* values. Shell environment variables can still override the defaults for one-off runs.
| Variable | Purpose |
|---|---|
CYPRESS_BASE_URL | Frontend URL used by Cypress. Local E2E scripts default this from FRONTEND_HOST_PORT, usually http://localhost:3001. |
CYPRESS_BACKEND_URL | Backend API URL used by cy.api and auth intercepts. Local E2E scripts default this from BACKEND_HOST_PORT, usually http://localhost:8002. |
CYPRESS_AUTH_MODE | Auth behavior for the run. |
CYPRESS_TEAM | Optional default team used by mocked users. |
CYPRESS_COLLABORATOR | Collaborator context. Defaults to isgs. |
CYPRESS_RESET_DB | Restores the sample database before specs that call cy.resetSeedData. Local E2E scripts default this to true. |
CYPRESS_DB_SEED_COMMAND | Seed command used when reset is enabled. Local E2E scripts default this to node deployment/scripts/docker-e2e-stack.cjs seed. |
Backend modes
The Docker development and E2E stacks can run the backend from local source or from an image. The Cypress contract should work in either mode when the backend exposes the same API and sample seed data.
Set BACKEND_MODE=image when the frontend repo should test against a published backend image. Set BACKEND_MODE=source or leave BACKEND_MODE=auto when a sibling backend checkout should be used locally.
For local E2E, these values live in deployment/.env.e2e:
BACKEND_MODE=auto
DB_CONNECTION=mongodb://mongodb:27017
DB_NAME=isgs_e2e
REQUIRE_AUTH=false
Use a disposable E2E database name. Do not point full workflow tests at a database containing hand-curated local, staging, or production data.
REQUIRE_AUTH=false keeps the backend API reachable to Cypress and the app. Cypress still mocks /check_auth by default so protected frontend routes consistently render instead of redirecting to /login.
Mocking policy
The E2E suite should use the real frontend and backend for OGRRE workflows. Mock external services at the boundary when a live integration would make tests slow, flaky, expensive, or credential-dependent. Common candidates are cloud uploads, export downloads, and third-party auth responses.
Avoid mocking backend OGRRE APIs in full workflow specs. If a backend behavior must be stubbed, keep it scoped to a frontend-only auth, permission, or error-state assertion.