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, and runs Cypress with CI-oriented settings.

CI uses the same E2E harness as local development: npm run docker:e2e plus npm run e2e:ci. The CI command uses the local Cypress wrapper with Chrome enabled.

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 npm run docker:e2e.
  6. Wait for http://localhost:8002/docs and http://localhost:3001.
  7. Run npm run e2e:ci.
  8. Upload Cypress screenshots and videos when a run fails.
  9. 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_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

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.

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 sets BACKEND_MODE=image so the frontend workflow validates against the configured backend image. Local runs can leave BACKEND_MODE=auto to use a sibling backend checkout when one exists.

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.