Testing Strategy

Relevant source files

The following files were used as context for generating this wiki page:

• server/common/sync/paginate/paginateIntegration.test.ts
• server/common/sync/providers/tests/dynamodb.provider.test.ts
• test-setup.js
• WARP.md
• deployment/README.md

The testing strategy for the Nucleus project focuses on ensuring the reliability and correctness of backend services, particularly data synchronization and workspace integrity. The approach is heavily centered on integration tests that validate functionality against real database providers like DynamoDB and SurrealDB.

The primary testing framework is vitest, used for structuring test suites, running assertions, and managing the test lifecycle. Tests are executed via npm scripts and are integrated into the CI/CD pipeline, which also includes Static Application Security Testing (SAST).

Tooling and Execution

The project relies on a standard set of tools for testing.

Tool / Command	Description	Source
vitest	The core testing framework used for writing and running tests with describe, it, and expect blocks.	server/common/sync/paginate/paginateIntegration.test.ts:1
npm run test	The main command to execute all tests within the monorepo.	WARP.md:53
GitLab CI/CD	The platform used for continuous integration, which includes running tests and security analysis (SAST) on code changes.	deployment/README.md:29-32

Workspace Integrity Check

Before running tests or builds, a verification script ensures the monorepo's structure is correct. This script, test-setup.js, is a simple Node.js utility that validates the Turbo workspace configuration.

The script performs the following checks:

1. Packages: Verifies that all expected shared libraries exist in the packages/ directory.
2. Product Apps: Confirms that all product application directories exist within client/products/ and contain a package.json file.
3. Turbo Configuration: Checks for the presence of the root turbo.json and package.json files.

Sources: test-setup.js

The following diagram illustrates the workflow of the workspace setup verification script.

Integration Testing

The core of the testing strategy is integration testing, which validates the interaction between different parts of the system, especially the API and the database.

Test Lifecycle and Environment

Tests are designed to be isolated and repeatable using vitest's lifecycle hooks.

Hook	Purpose	Example Usage	Source
beforeAll	One-time setup before all tests in a file.	Cleaning up test data, setting process.env.SYNC_PROVIDER.	server/common/sync/paginate/paginateIntegration.test.ts:10-13
afterAll	One-time teardown after all tests in a file.	Final cleanup of test data.	server/common/sync/paginate/paginateIntegration.test.ts:15-18
beforeEach	Runs before each it block.	Initializing a new DynamoDBSyncProvider instance.	server/common/sync/providers/__tests__/dynamodb.provider.test.ts:33-41

To handle the eventual consistency of databases like DynamoDB, a sleep utility is used to introduce delays between write and read operations, ensuring that assertions are made against up-to-date data.

Sources: server/common/sync/providers/tests/dynamodb.provider.test.ts:12, 110

Data Synchronization Testing

A significant portion of the tests covers the data synchronization logic (cloneUp, paginate, syncUp, syncDown). These tests are provider-agnostic and can be run against different database backends by changing the SYNC_PROVIDER environment variable.

The following sequence diagram shows a typical integration test for the paginate function.

This diagram illustrates the flow where test data is first created, then paginated results are fetched and verified.

Sources: server/common/sync/paginate/paginateIntegration.test.ts:32-84

Database Provider-Specific Tests

In addition to general sync tests, there are detailed integration tests for specific database providers. The dynamodb.provider.test.ts file provides comprehensive coverage for the DynamoDBSyncProvider.

Key test scenarios include:

• Mutation Handling: Correctly processing CREATE, DELETE, and MERGE mutations during a syncUp.
• Batch Operations: Ensuring cloneUp correctly splits large batches of records into multiple requests to respect DynamoDB's 25-item limit per batch write.
• Data Reconciliation: Verifying that the reconcile method successfully identifies and removes malformed data (e.g., nodes missing a contentType).
• Error Handling: Gracefully handling errors from invalid configurations, such as a non-existent table name.

The sequence diagram below shows the test flow for a MERGE mutation against the DynamoDB provider.