Testing Environments

Explains how the local Docker and staging environments differ and how to configure Cypress for each.

---

Local Docker

The default setup. All services run on your laptop via docker compose.

How networking works

The cypress service uses network_mode: host, which means the container shares the host machine's network stack instead of running in an isolated Docker network. This allows:

• http://localhost:3000 → portals SPA (served by the portals container, port 3000 mapped to host)
• http://localhost:8000 → Django API (served by the django container, port 8000 mapped to host)

Without network_mode: host, localhost inside the Cypress container would refer to the container itself, and calls to localhost:3000 / localhost:8000 would fail with ECONNREFUSED. Using Docker service names (portals:3000) does not work either, because the SPA's API client is configured at runtime from VITE_SWAGGER_SCHEMA_URL — it always points to localhost:8000 from the browser's perspective. If the SPA is loaded from portals:3000, its subsequent API calls to localhost:8000 fail because the browser's localhost is still the host machine, not the Docker network.

network_mode: host is a Linux feature. On macOS/Windows Docker Desktop uses a VM, so this setting is effectively ignored and the behaviour differs. The local Docker setup is intended for Linux only.

Env file

testing/apps/novahomecare/.env — copy from .env.development.example, no edits needed.

All URLs use localhost:3000 / localhost:8000 for the reasons above.

---

Staging

Tests run against a live hosted environment rather than local containers. The setup differs in several ways:

Concern	Local Docker	Staging
Base URL	http://localhost:3000	https://<staging-domain>
API	http://localhost:8000	https://api.<staging-domain>
Org tokens	From local Django fixtures	Must match tokens in the staging DB
Admin credentials	superadmin@novavirtual.site / a1234	Real staging credentials (keep out of repo)
Fixture loading	Required (loaddata + seed script)	Not required — staging DB is persistent
network_mode	host (Linux localhost resolution)	Not needed — all URLs are public HTTPS

Running against staging

Create a separate env file (not committed):

cp testing/apps/novahomecare/.env.development.example testing/apps/novahomecare/.env.staging

Edit .env.staging:

• Replace all http://localhost:3000 with the staging base URL
• Replace all http://localhost:8000 references (these are internal to the SPA — the SPA must be built pointing at the staging API already)
• Replace org tokens with the real tokens from the staging DB
• Replace admin credentials with real staging credentials
• Replace employee/marketer credentials if different

Run Cypress pointing at the staging env file:

docker compose run --rm -e ENV_FILE=.env.staging cypress sh -c "npm install && cypress run"

Or override the env file in the compose service definition for a staging-specific run.

Note: The cypress service definition uses env_file: ./testing/apps/novahomecare/.env. To target staging without editing the service definition, pass env vars individually with -e KEY=value flags or mount a different env file.

---

Debugging Test Failures

Screenshots

On failure Cypress captures a screenshot automatically:

testing/apps/novahomecare/cypress/screenshots/

HTML Report

After any headless run:

docker compose up reports
# open http://localhost:8090

Known issues found during local setup

Application form tests — URL concatenation bug (fixed)

The step the user navigate to the application form '<enviroment>','<business>' used to concatenate two env var values:

cy.visit(Cypress.env(enviroment) + Cypress.env(business));
// e.g. "http://localhost:3000/login/<token>" + "http://localhost:3000/apply-now/<token>"
// → invalid URL → React Router 404 wildcard route

Fixed to use only Cypress.env(business) since the application_form_* env vars already contain the full URL.

Login post-login assertions — brittle Chakra selectors

Three login tests fail on p.chakra-text.css-6q9ebm. The generated Chakra class css-6q9ebm is build-time deterministic but changes when the component tree changes. The login itself succeeds; only the role-verification assertion fails. See To Review.

network_mode: host — Linux only

On macOS or Windows Docker Desktop, network_mode: host is silently ignored. Cypress will be in an isolated container network and localhost URLs will resolve to the container itself → ECONNREFUSED. To run locally on macOS/Windows you would need to map service names or use host.docker.internal and rebuild the SPA accordingly.