Testing Strategy (Unit, Integration, E2E)
Relevant source files
The following files were used as context for generating this wiki page:
GoGovSG employs a multi-layered testing strategy to ensure the reliability of the link shortener service. This strategy consists of unit tests for isolated logic, integration tests for API and database interactions, and end-to-end (E2E) tests for validating critical user journeys.
The following table summarizes the primary testing frameworks and tools used across the project:
| Test Layer | Framework / Tool | Location |
|---|---|---|
| Unit Testing | Jest | src/server/modules/**/__tests__ |
| Integration Testing | Jest / Supertest | test/integration |
| E2E Testing | Playwright | test/end-to-end |
Sources: package.json:20-25, playwright.config.ts:5-8
Unit Testing
Unit tests focus on the smallest testable parts of the application, such as individual functions, services, and controllers. GoGovSG uses Jest to execute these tests and mock external dependencies like repositories or mailers.
Service and Repository Testing
Service tests validate business logic by mocking database repositories. For example, JobManagementService.test.ts mocks JobRepository and UserRepository to test job creation and status polling without actual database side effects. Repository tests, such as UrlRepository.test.ts, use mocked Sequelize models and Redis clients to verify data access logic.
The diagram above shows how unit tests isolate the service layer using mocks.
Sources: src/server/modules/job/services/tests/JobManagementService.test.ts:10-50, test/server/repositories/UrlRepository.test.ts:25-50
Controller Testing
Controller unit tests verify request handling, input validation, and response formatting. The OneGovSgController.test.ts validates that the authentication controller correctly handles OIDC callbacks, rejects mismatched issuers, and manages session regeneration.
Sources: src/server/modules/auth/tests/OneGovSgController.test.ts:60-150
Integration Testing
Integration tests verify that different modules of the application work together, specifically focusing on the interaction between the API server and the PostgreSQL database.
API Integration
Integration tests send actual HTTP requests to a running test instance of the server. They validate:
- Authentication: Ensuring endpoints correctly require auth cookies or API keys.
- CRUD Operations: Verifying that creating a link via the API correctly persists data to the database.
- External APIs: Testing Version 1 of the external API for consistency.
Sources: test/integration/api/user/Urls.test.ts:55-120, test/integration/api/external-v1/Urls.test.ts:70-110
Test Environment Management
The project uses specific scripts to manage the test database and environment:
pnpm run db:migrate:test: Runs migrations on the test database.pnpm run test:integration: Executes the integration test suite.
Sources: package.json:30-40
End-to-End (E2E) Testing
E2E tests validate the entire system from the user's perspective by automating browser interactions. Playwright is the primary tool for these tests, covering features like URL creation, file uploads, and transitions.
Playwright Configuration
The E2E suite is configured to run serially (workers: 1) to avoid race conditions in the shared maildev inbox used for OTP authentication. Tests are matched via the **/*.spec.ts pattern and target the rootLocation of the local development server.
Sources: playwright.config.ts:10-15, playwright.config.ts:55-60
Key E2E Scenarios
E2E tests cover high-stakes user flows:
- Link Creation: Validates the "Create Link" modal, short URL generation, and tag assignment.
- File Uploads: Tests size limits (e.g., rejecting files > 20MB) and malicious file detection.
- Redirect Behavior: Verifies that active links redirect correctly while inactive links show a 404/unavailable page.
- Transition Pages: Ensures the safety transition page appears for new links and times out after ~6 seconds.
The sequence shows the end-to-end flow for creating and accessing a file-based shortlink.
Sources: test/end-to-end/UrlCreation.spec.ts:150-180, test/end-to-end/TransitionPage.spec.ts:35-55
Test Automation and CI
GoGovSG integrates testing into the development workflow using scripts in package.json.
| Command | Description |
|---|---|
pnpm run test | Runs all Jest unit tests. |
pnpm run test:ci | Runs unit tests with coverage reporting for CI pipelines. |
pnpm run test:e2e-headless | Runs Playwright tests in a headless browser environment. |
pnpm run lint | Uses oxlint to identify code quality issues before testing. |
Sources: package.json:20-28
Summary
The GoGovSG testing strategy combines Jest for granular logic verification and Playwright for functional validation. By isolating services with unit tests and validating full-stack behavior through integration and E2E tests, the project maintains high reliability for official government link shortening services.