Testing Strategies (E2E & Unit)
Relevant source files
The following files were used as context for generating this wiki page:
Testing within the Twenty ecosystem follows a structured pyramid approach, prioritizing behavior over implementation details. The strategy encompasses unit testing for individual functions and utilities, integration testing for cross-module functionality, and end-to-end (E2E) testing for full user workflows. The project emphasizes a 70/20/10 distribution: 70% unit tests, 20% integration tests, and 10% E2E tests.
Sources: CLAUDE.md:167-167, packages/twenty-codex-plugin/references/develop-app/tests.md:3-5
Core Testing Principles
The project adheres to specific technical principles to ensure test reliability and maintainability:
- Test Behavior: Focus is placed on the user's perspective rather than internal implementation.
- Querying Strategy: Selection of elements is performed via user-visible attributes (text, roles, labels) instead of internal test IDs where possible.
- Isolation: Mocks are cleared between tests using
jest.clearAllMocks()to prevent state leakage. - Naming Conventions: Test names follow the pattern "should [behavior] when [condition]".
Sources: CLAUDE.md:166-172
Testing Pyramid and Distribution
The architecture utilizes different testing levels to balance execution speed with coverage depth.
This diagram illustrates the recommended distribution of tests within the repository to ensure a fast feedback loop while maintaining system-wide confidence.
Sources: CLAUDE.md:167-167
Unit Testing
Unit tests are the foundation of the testing strategy, covering isolated logic and pure functions. They are executed using Jest for most packages and node:test for specific plugin validators.
Organization and Scope
Unit tests (*.spec.ts) are located in sibling __tests__/ directories adjacent to the source code they cover. For app development, every utility or function file must have a corresponding spec file.
| Component Category | Testing Focus |
|---|---|
| Parsers | API shape handling, missing fields, and empty responses. |
| Mappers | Data transformation logic, including "no match" scenarios. |
| Front-component Helpers | Payload builders, result parsing, and snackbar formatting. |
| Logic Functions | Bulk record normalization and payload shapes. |
| Post-install Hooks | Idempotency (ensuring identical state after multiple runs). |
Sources: packages/twenty-codex-plugin/references/develop-app/tests.md:3-23, packages/twenty-codex-plugin/skills/develop-app/SKILL.md:59-60
Unit Test Execution Examples
The project uses specific commands for different packages:
- Frontend:
npx nx test twenty-front - Backend:
npx nx test twenty-server - Validators:
yarn workspace twenty-codex-plugin validate(which runs internal validator tests).
Sources: CLAUDE.md:33-35, packages/twenty-codex-plugin/AGENTS.md:77-78
Integration Testing
Integration tests verify that different parts of the system work together, particularly involving the database and API.
Environment Isolation
A critical rule in the project's strategy is that integration tests must run against an isolated test instance rather than the development instance. This prevents tests from polluting the development workspace or interfering with active synchronization.
The diagram shows the mandatory separation between the development port (2020) and the integration test port (2021).
Sources: packages/twenty-codex-plugin/references/develop-app/tests.md:29-37, packages/twenty-codex-plugin/scripts/validators/cross-doc-contracts.js:283-287
Execution Commands
Integration tests require starting a specific Docker container for the test instance:
# Start isolated test instance
yarn twenty docker:start --test
# Run tests targeting the test instance
TWENTY_API_URL=http://localhost:2021 yarn test
Sources: packages/twenty-codex-plugin/references/develop-app/tests.md:38-41, packages/twenty-codex-plugin/AGENTS.md:46-48
End-to-End (E2E) Testing
E2E tests use Playwright to simulate real user interactions across the entire stack.
Key Characteristics
- Scope: Covers full user flows, such as authentication and record management.
- Tooling: Managed via the
twenty-e2e-testingpackage. - Authentication: When testing UI E2E, the standard procedure is to click "Continue with Email" and use prefilled credentials.
Sources: CLAUDE.md:41-41, CLAUDE.md:95-95
Automated Plugin Validation
Specific to the twenty-codex-plugin, an automated validation script enforces structural and metadata compliance.
Validation Flow
The validate.js script runs a series of assertions to ensure the plugin's integrity before release.
The sequence diagram illustrates how the validation script orchestrates multiple specialized validators to confirm plugin compliance.
Sources: packages/twenty-codex-plugin/scripts/tests/validate.spec.js:46-75, packages/twenty-codex-plugin/scripts/validators/cross-doc-contracts.js:1-15
Validation Checks Table
| Check Name | Target File | Purpose |
|---|---|---|
assertJsonMetadata | plugin.json / package.json | Ensures version sync and valid manifest paths. |
assertInterfaceFields | plugin.json | Validates marketplace metadata, descriptions, and branding. |
assertSkills | skills/<name>/SKILL.md | Confirms canonical skill presence and frontmatter validity. |
assertReferences | references/*.md | Verifies existence of all required documentation files. |
assertSetupHelper | scripts/setup-mcp.sh | Validates syntax and URL normalization logic. |
Sources: packages/twenty-codex-plugin/scripts/tests/validate.spec.js:134-180, packages/twenty-codex-plugin/scripts/validators/references.js:5-22
Summary
The Twenty testing strategy combines rigorous unit testing for logic isolation with mandatory environment separation for integration and E2E tests. By enforcing a 70/20/10 pyramid and requiring isolated test instances on port 2021, the project ensures that high-velocity development does not compromise system stability or data integrity. Automated validators further extend this protection to the plugin ecosystem, ensuring all extensions meet platform-wide quality standards.
Sources: CLAUDE.md:167-172, packages/twenty-codex-plugin/references/develop-app/tests.md:29-37