Testing Setup

All tests run via Docker Compose from the parent repo root. Do not cd into any submodule and run commands directly.

---

testing-v2/ Setup (active suite)

The E2E suite runs against an isolated test stack (portals-test on port 3001, django-test on port 8001, separate nhc_test database). The dev database is never touched.

Prerequisites

• Docker and Docker Compose running
• testing-v2/.env exists — make build copies it automatically from .env.example
• inotify watcher limit raised (one-time, Linux only):

echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf && sudo sysctl -p

Two concurrent Vite dev servers exhaust the default Linux inotify limit. Without this, portals-test crashes with ENOSPC.

Running the full suite

make test-run

This does everything in one command: starts the test stack, waits for portals-test to be ready, seeds the test database, runs Cypress headless, then tears the stack down.

Running a single feature folder

Faster feedback when working on a specific journey. Start the test stack first, then run Cypress manually:

make test-up
make test-seed   # once, or after make test-clean
docker compose --profile test run --rm e2e-v2 sh -c "npm install && cypress run --spec 'cypress/e2e/features/01_login/**/*.feature'"

Running a single feature file

docker compose --profile test run --rm e2e-v2 sh -c "npm install && cypress run --spec 'cypress/e2e/features/01_login/login.feature'"

Headed mode (watch tests run in a browser)

Headed mode runs Cypress directly on the host against the dev stack (port 3000), not the test stack. Use it when developing or debugging a specific spec.

Prerequisites

• Dev stack must be running: make up from the parent root
• Node 24 via nvm — testing-v2/ has a .nvmrc pinned to 24:

cd testing-v2
nvm use        # picks up .nvmrc

• node_modules must be installed by the host user (not Docker — Docker writes as root and causes EACCES):

# If node_modules is missing or root-owned:
sudo rm -rf node_modules
npm install

• If cypress/screenshots or cypress/reports are root-owned from a previous Docker run:

sudo chown -R $(whoami) cypress/screenshots cypress/reports

Running headed

From inside testing-v2/:

Full suite:

BASE_URL=http://localhost:3000 npx cypress run --headed --browser chrome --config defaultCommandTimeout=8000

Single spec:

BASE_URL=http://localhost:3000 npx cypress run --headed --browser chrome --config defaultCommandTimeout=8000 --spec cypress/e2e/features/01_login/login.feature

defaultCommandTimeout=8000 gives each command 8 seconds before timing out, which naturally slows the visible pace so you can follow execution.

Running against staging

Override BASE_URL to point at any environment — credentials in .env must match what exists on that environment:

BASE_URL=https://staging-portals.novavirtual.site npx cypress run --headed --browser chrome --spec cypress/e2e/features/01_login/login.feature

Why not cypress open?

The Cypress interactive GUI (cypress open) is an Electron app that crashes on this machine due to a GPU/IPC issue (bad_message.cc reason 114). Use cypress run --headed instead — it launches Chrome directly without the Electron wrapper and behaves identically.

---

Resetting the test stack

make test-clean   # wipe test stack volumes and images
make test-run     # rebuild and re-seed from scratch

Test Personas

Two admin-level personas are seeded for testing. Use the right one for the feature under test — they have different permissions and UI surfaces.

Persona	Email	Password	Role	Org scope
Master	superadmin@novavirtual.site	a1234	ROLE_MASTER	All orgs
Admin	admin@novavirtual.site	Test1234!	ROLE_ADMIN	Nova Home Care only
Employee	employee@novavirtual.site	Test1234!	ROLE_EMPLOYEE	Nova Home Care
Marketer	marketer@novavirtual.site	Test1234!	ROLE_MARKETER	Nova Home Care

Master vs Admin — key differences:

Feature	Master	Admin
Org switcher (top bar)	✅	✗
Audit Log tab in sidebar	✅	✗
Notifications	✗	✅
Scoped to one org	✗	✅

The Master user (ROLE_MASTER) is created automatically by Django on startup via DJANGO_SUPERUSER_* env vars in django-api/.env. The Admin user and all other test personas are created by the seed script in step 3.

When writing tests: use Master for anything that touches cross-org behaviour or Audit Log. Use Admin for the standard single-org administrator experience — this is what a real site admin will see day-to-day.

Environment Variables

The .env file lives at testing-v2/.env. Three variables cover everything needed for the Nova Home Care org:

Variable	Default	Description
BASE_URL	http://localhost:3001	portals-test SPA URL — localhost because the service uses network_mode: host
NOVA_ORG_TOKEN	5ae807a7-df99-4bc2-8d51-fa808b81a41e	Nova Home Care org token (set by Django fixture)
ADMIN_EMAIL	superadmin@novavirtual.site	Django superuser (set by DJANGO_SUPERUSER_EMAIL)
ADMIN_PASSWORD	a1234	Django superuser password (set by DJANGO_SUPERUSER_PASSWORD)

Why localhost and network_mode: host: The SPA's API client is configured at build time to call localhost:8000. If Cypress ran in an isolated Docker network, localhost inside the container would resolve to the container itself, not the host. network_mode: host shares the host's network stack so that both localhost:3000 (SPA) and localhost:8000 (Django) are reachable. This is a Linux-only Docker feature; on macOS/Windows Docker Desktop it is silently ignored — see Environments for alternatives.

Resetting After make clean

make clean wipes all volumes including the database. Re-run fixtures and (if needed) seed scripts before testing again:

make up
docker compose run --rm django sh -c "python manage.py loaddata novahomecareapi/fixtures/*.json"

---

testing/ Setup (legacy — reference only)

The original suite is no longer run or maintained. The setup instructions are preserved here for reference if you need to cross-check a legacy test.

1. Copy the env file

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

2. Load fixtures and seed test users

docker compose run --rm django sh -c "python manage.py loaddata novahomecareapi/fixtures/*.json"
docker compose run --rm django python manage.py shell < django-api/scripts/seed_test_users.py

3. Run the legacy suite

docker compose run --rm cypress

Do not use the cypress service for new test development. All new tests go in testing-v2/.