Skip to main content

E2E CI

The frontend repository includes .github/workflows/frontend-tests-dispatch.yml for reusable frontend validation. The workflow runs unit tests, starts the isolated Docker E2E stack, verifies service health, tests loading in both schema modes, and runs Cypress with CI-oriented settings.

CI uses the same E2E harness as local development. It runs npm run e2e:schema-modes in package mode, recreates the backend, and then runs npm run e2e:ci in database mode. Both Cypress commands use Chrome in CI.

Workflow shape​

The CI job should:

  1. Check out the frontend repository.
  2. Install Node dependencies with npm ci.
  3. Run unit tests with npm test -- --watchAll=false --runInBand.
  4. Create deployment/.env.e2e from deployment/.env.e2e.example.
  5. Start the isolated E2E Docker stack with USE_DB_PROCESSORS=false.
  6. Wait for http://localhost:8002/docs and http://localhost:3001.
  7. Run the focused schema-mode loading contract.
  8. Recreate the backend with USE_DB_PROCESSORS=true.
  9. Verify the backend reports database mode and run the full E2E suite.
  10. Upload Cypress screenshots, videos, and backend logs.
  11. Stop and remove the E2E stack with npm run docker:e2e:clean.

CI Cypress environment​

The Cypress CI command derives defaults from deployment/.env.e2e through deployment/scripts/run-cypress-e2e.cjs:

CYPRESS_BASE_URL=http://localhost:3001
CYPRESS_BACKEND_URL=http://localhost:8002
CYPRESS_AUTH_MODE=mock
CYPRESS_COLLABORATOR=isgs
CYPRESS_USE_DB_PROCESSORS=<USE_DB_PROCESSORS from deployment/.env.e2e>
CYPRESS_RESET_DB=true
CYPRESS_DB_SEED_COMMAND=node deployment/scripts/docker-e2e-stack.cjs seed

The backend should run with:

REQUIRE_AUTH=false
REACT_APP_BACKEND_URL=http://localhost:8002
DB_NAME=isgs_e2e
USE_DB_PROCESSORS=false

This keeps the full workflow suite focused on application behavior instead of external authentication setup. The backend auth flag allows real API requests, while Cypress mocks the frontend /check_auth response to prevent login redirects during protected-route reloads. The package-mode pass verifies loading only. The workflow switches explicitly to USE_DB_PROCESSORS=true before the full suite so database schema mutation tests still run once.

Database reset​

The E2E Docker stack restores deployment/mongo-dumps/sample_mongodump when the Mongo volume is first created. Cypress also sets CYPRESS_RESET_DB=true, so specs that call cy.resetSeedData restore the sample dump before mutating records.

node deployment/scripts/docker-e2e-stack.cjs seed

For non-Docker environments, provide a seed command explicitly:

CYPRESS_DB_SEED_COMMAND="your seed command" npm run e2e:ci

The command runs from the frontend repository root.

Backend source or image​

CI builds the backend from source. Push/PR runs use backend main; manually dispatched App Tests runs accept backend_repository and backend_ref to test coordinated frontend/backend changes. Local runs can leave BACKEND_MODE=auto to use a sibling backend checkout or set BACKEND_MODE=source explicitly. Use an updated checkout when testing lightweight loading and missing-schema fallbacks. Image-mode runs require a newly published backend image with those changes; restarting an old image does not update its code.

For source-backed CI runs, make sure backend-only runtime dependencies, including any required processor or data-cleaning packages, are available before starting the Docker stack.

Artifacts​

Cypress writes runtime artifacts to:

  • cypress/screenshots/
  • cypress/videos/
  • cypress/downloads/

These paths are ignored by git. CI should upload screenshots and videos on failure so the failing screen state is preserved outside the repository.

Troubleshooting​

If Cypress fails before tests start with a binary verification error, clear or reinstall the local Cypress binary cache, then rerun:

./node_modules/.bin/cypress verify

If tests cannot reach the app, confirm:

  • The frontend URL matches CYPRESS_BASE_URL.
  • The backend URL matches CYPRESS_BACKEND_URL and returns from /health or /docs.
  • CYPRESS_AUTH_MODE=mock is set, and the backend still has REQUIRE_AUTH=false.
  • deployment/.env.e2e exists and matches the E2E stack ports.
  • Seed data exists and matches cypress/fixtures/seeded-data.json.