Testing
Photonix has two types of tests: Python backend tests (pytest) and frontend end-to-end tests (Playwright).
Backend Tests (Python/pytest)
We have Python tests to cover most of the the server-side logic. We use pytest as a test runner and recommend running the tests inside the Docker container.
If you have the code checked out and can run Makefiles then you can start the container if it isn't already running:
make start
If you can't run the Makefile directly (e.g. if you're on Windows) then you can see what the equivalent command would be by looking inside that file. The command for starting the environment with out make is:
docker compose -f docker/docker-compose.dev.yml up
In another teminal connect to the Photonix Docker container and execute the test runner:
make shell
python test.py
To start the shell without make would be:
docker compose -f docker/docker-compose.dev.yml exec photonix bash
If you are only interested in a particular test and want to save time you can add the test file path as an extra argument, i.e:
python test.py tests/test_metadata.py
If you are familiar with pytest then you can add extra arguments to the end and they will be passed through.
If you are an expert with pytest and have suggestions for improving this setup then please do get in touch with your suggestions.
Frontend Tests (Playwright)
We use Playwright for end-to-end testing of the React frontend. These tests run against the actual application in Docker containers and test real user flows.
Prerequisites
Make sure the development environment is running:
make start
Then install Playwright dependencies in the ui directory:
cd ui
npm install
npx playwright install
Running Tests
Run all Playwright tests:
cd ui
npx playwright test
Run a specific test file:
npx playwright test e2e/auth.spec.ts
Run tests in headed mode (see the browser):
npx playwright test --headed
Run tests with UI mode for debugging:
npx playwright test --ui
Test Configuration
Tests are configured to run serially (one at a time) because they share the same database. This is set in ui/playwright.config.ts.
Test Data Setup
Playwright tests create their own test data using Django management commands executed via Docker. The shared test utilities in ui/e2e/test-utils.ts provide helpers for:
setupTestUser(username, password)- Creates a test user with a fully configured library (required to bypass onboarding redirects)cleanupTestUser(username)- Removes the test user and all associated data (library, library paths, etc.)login(page, username, password)- Logs in with the specified credentialscreateTestPhotos(username, count, options)- Creates test photos (solid colour images, optionally tagged) in the user's librarycleanupTestPhotos(username)- Removes the test photos and tagsrunDjangoCommand(pythonCode)- Executes arbitrary Python code in the Django shell via Docker
Example usage in a test:
import { setupTestUser, cleanupTestUser, login } from './test-utils'
test.beforeAll(async () => {
setupTestUser('myuser', 'mypassword')
})
test.afterAll(async () => {
cleanupTestUser('myuser')
})
test('my test', async ({ page }) => {
await login(page, 'myuser', 'mypassword')
// ... test assertions
})
Viewing Test Reports
After running tests, Playwright generates an HTML report. To view it:
npx playwright show-report
This opens a browser with detailed results including:
- Pass/fail status for each test
- Test duration
- Screenshots and traces for failed tests
- Error messages and stack traces
Test Structure
The test files are located in ui/e2e/:
auth.spec.ts- Authentication flows (login, logout, session persistence)onboarding.spec.ts- New user onboarding wizardlibrary-switching.spec.ts- Library selection and switchinginvite.spec.ts- Adding users to libraries and invitation linkssettings.spec.ts- Settings area (password and profile changes)thumbnails.spec.ts- Thumbnail grid and selectionsearch.spec.ts- Search bar, autocomplete and filtersphoto-detail.spec.ts- Photo detail view and keyboard navigationbounding-boxes.spec.ts- Object bounding boxes on the photo detail viewimage-resolution.spec.ts- Image resolution chosen for viewport size and pixel densitytile-zoom.spec.ts- Tiled zooming of large images
Debugging Failed Tests
When a test fails, Playwright captures useful debugging information:
- Screenshots - Automatically captured at the point of failure
- Traces - Recorded on first retry (configurable in
playwright.config.ts) - Error context - Saved in
test-results/directory
To view a trace file:
npx playwright show-trace test-results/path-to-trace.zip
For interactive debugging, use the --debug flag:
npx playwright test --debug