Testing¶

Test Environment Setup¶

source .venv/bin/activate
inv test.setup

This command:

Updates npm and Python dependencies
Builds Docker images
Populates test database
Starts test containers

Playwright E2E Tests (Recommended)¶

Playwright is the recommended E2E testing framework with parallel execution and better performance.

Quick Start¶

# Install browsers (first time only)
inv test.playwright.install

# Run all tests headless
inv test.playwright.headless

# Run tests with visible browser
inv test.playwright.headed

# Open interactive UI mode
inv test.playwright.ui

Run Specific Test Suites¶

inv test.playwright.navigation    # Navigation tests
inv test.playwright.tournament    # Tournament tests
inv test.playwright.draft         # Draft tests
inv test.playwright.bracket       # Bracket tests
inv test.playwright.league        # League tests
inv test.playwright.herodraft     # HeroDraft tests
inv test.playwright.mobile        # Mobile responsive tests

Performance Options¶

# Run with specific worker count
inv test.playwright.headless --args="--workers=4"

# Run specific shard (for debugging CI)
inv test.playwright.headless --args="--shard=1/4"

Debugging¶

# Debug mode with inspector
inv test.playwright.debug

# View HTML report
inv test.playwright.report

See Playwright Testing Guide for comprehensive documentation.

Cypress E2E Tests (Legacy)¶

Interactive Mode¶

inv test.open

Opens Cypress Test Runner for interactive debugging.

Headless Mode¶

inv test.headless

Runs all tests in headless mode (CI/CD).

Run Specific Test Specs¶

inv test.spec --spec drafts      # Run draft tests only
inv test.spec --spec tournament  # Run tournament tests
inv test.spec --spec navigation  # Run navigation tests

Available spec shortcuts:

Shortcut	Pattern
`drafts`	`tests/cypress/e2e/07-draft/*/.cy.ts`
`tournament`	`tests/cypress/e2e/04-tournament/*/.cy.ts`
`tournaments`	`tests/cypress/e2e/03-tournaments/*/.cy.ts`
`navigation`	`tests/cypress/e2e/01-*.cy.ts`
`mobile`	`tests/cypress/e2e/06-mobile/*/.cy.ts`

Test Location¶

Playwright (Recommended)¶

frontend/tests/playwright/
├── e2e/           # Test specs organized by feature
├── fixtures/      # Test fixtures and auth helpers
├── helpers/       # Page objects and utilities
└── global-setup.ts # Pre-test data caching

Cypress (Legacy)¶

frontend/tests/cypress/
├── e2e/           # Test specs
├── fixtures/      # Test data
└── support/       # Custom commands

Authentication Helpers¶

Custom Cypress commands for authentication:

cy.loginUser()           // Regular user
cy.loginStaff()          // Staff user
cy.loginAdmin()          // Admin user
cy.loginAsUser(userPk)   // Login as specific user by PK

For testing captain-specific flows, use loginAsUser to login as any user:

// Login as captain to test draft picks
cy.loginAsUser(captainPk).then(() => {
  cy.visit(`/tournament/${tournamentPk}?draft=open`)
  // Draft modal auto-opens, captain can pick
})

Get Tournament by Key¶

For tests that need specific tournament configurations:

cy.getTournamentByKey('captain_draft_test').then((response) => {
  const tournamentPk = response.body.pk
  cy.visit(`/tournament/${tournamentPk}`)
})

API Testing Pattern¶

import { apiBasePath } from '~/components/api/axios'

cy.loginAdmin().then(() => {
  cy.request('POST', `${apiBasePath}/items/`, { name: 'Test' })
  cy.visit('/')
  cy.contains('Test').should('exist')
})

Best Practices¶

Real Backend Testing

This project tests against the real backend. Don't stub API calls with cy.intercept() for E2E tests.

Use cy.request() for setup/teardown
Import apiBasePath from axios config
Use stable selectors (data-testid, id)
Keep tests isolated and independent

Backend Tests¶

source .venv/bin/activate
cd backend
python manage.py test

Worktree Testing Verification¶

When working in a git worktree (e.g., .worktrees/feature-name), you must verify the full stack works before completing the branch (merge, PR, or discard).

Why Worktrees Need Special Attention¶

Worktrees have isolated environments with separate databases
Unit tests alone don't catch integration issues (database, Docker, nginx routing)
The test environment verifies frontend-backend integration works

Required Verification Steps¶

From the worktree root directory:

cd /home/kettle/git_repos/website/.worktrees/feature-name

# 1. Source the worktree's virtual environment
source .venv/bin/activate

# 2. Stop any existing test environment
inv test.down

# 3. Run full test setup (builds images, installs deps)
inv test.setup

# 4. Run database migrations for test environment
inv db.migrate.test

# 5. Populate test data
inv db.populate.all

# 6. Run backend tests in Docker
inv test.run --cmd 'python manage.py test app.tests -v 2'

# 7. Start test environment
inv test.up

# 8. Run Playwright smoke tests (recommended)
inv test.playwright.headless

Quick Verification (Minimum)¶

If full Cypress tests aren't required, at minimum:

Run inv test.up and verify containers start without errors
Navigate to https://localhost in browser
Verify login works and pages load without database errors
Check browser console for JavaScript errors

Common Issues¶

Issue	Solution
Database errors on page load	Run `inv db.migrate.test` and `inv db.populate.all`
Container won't start	Run `inv test.down` then `inv test.setup`
WebSocket connection failed	Check nginx config routes `/api/` correctly (WebSockets use /api/ paths)
Missing dependencies	Run `inv test.setup` to rebuild images