Testing Strategy

Relevant source files

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

• package.json
• src/lib/tests/app-service.test.ts
• src/lib/services/workspace/methods/tests/crud.test.ts
• src/app/api/services/workspace/upload/tests/route.test.ts
• src/lib/forms/(viral-tools)/sars-cov2-genome-analysis/tests/sars-cov2-genome-analysis-form-utils.test.ts
• src/lib/tests/rerun-utility.test.ts
• src/lib/services/workspace/tests/helpers.test.ts

The testing strategy for the dxkb project is built around a robust suite of unit and integration tests designed to ensure the reliability of service interactions, workspace management, and complex form transformations. The project utilizes Vitest as its primary test runner, complemented by Mock Service Worker (MSW) for network interception and Testing Library for DOM-related assertions.

The strategy focuses on validating the core business logic, including the transformation of user inputs into API-compatible parameters, the handling of workspace objects (CRUD operations), and the integration between frontend hooks and backend services. Testing is categorized into unit tests for utility functions, service-level tests for API interactions, and route-level tests for Next.js API endpoints.

Sources: package.json:11-13, src/lib/tests/app-service.test.ts:1-20

Core Testing Infrastructure

The project employs a modern TypeScript-based testing stack. The configuration supports running tests in a browser-like environment (jsdom) and provides tools for mocking both internal modules and external network requests.

Test Runner and Environment

Tool	Purpose	Configuration/Usage
Vitest	Main test runner	Execution via npm run test or vitest run
MSW (Mock Service Worker)	API Mocking	Used to intercept HTTP requests in app-service.test.ts and route.test.ts
jsdom	DOM Environment	Simulates a browser environment for React component and hook testing
@testing-library/react	Component Testing	Used for testing UI components and hooks

Sources: package.json:63-80, src/lib/tests/app-service.test.ts:1-10

Network Interception Flow

The project uses MSW to simulate backend responses, ensuring that service tests do not rely on a live API. This allows for testing edge cases like 404 errors, 500 server errors, and unauthorized access.

Unit Testing of Business Logic

Form Utilities and Transformations

A significant portion of the test suite is dedicated to form-utils. These utilities are responsible for sanitizing user input and transforming it into the specific JSON structures required by the BV-BRC backend services.

• Sanitization: Functions like sanitizeTaxonomyForOutputName and sanitizeSampleId remove special characters and whitespace to prevent downstream file system or API errors.
• Transformation: transformSarsCov2GenomeAnalysisParams and similar functions map complex form states (including paired-end and single-end libraries) into API parameters.

Sources: src/lib/forms/(viral-tools)/sars-cov2-genome-analysis/tests/sars-cov2-genome-analysis-form-utils.test.ts:47-100, src/lib/forms/(viral-tools)/sars-cov2-wastewater-analysis/tests/sars-cov2-wastewater-analysis-form-utils.test.ts:11-50

Workspace and Helper Utilities

Helper functions manage path normalization, permission checks, and data structure conversions.

• Path Normalization: normalizeWsPath is tested to ensure it handles leading/trailing slashes and double slashes correctly.
• Permissions: hasWriteAccess validates whether a user can modify a workspace object based on user_permission and global_permission flags.

Service and API Route Testing

AppService and WorkspaceClient

Tests for the AppService verify the correct mapping of method names (e.g., AppService.query_task_details) and the transformation of result tuples into structured objects.

• Mocking: The jsonrpc-client is frequently mocked to verify that the correct method strings and parameters are passed to the JSON-RPC layer.
• Job Control: Tests verify the conversion of numerical job IDs and boolean flags into the specific formats expected by the AppService API.

Sources: src/lib/tests/app-service.test.ts:31-60, src/lib/services/workspace/methods/tests/crud.test.ts:11-40

Next.js API Routes

API routes are tested using mockNextRequest and mockNextResponse helpers. These tests focus on:

• Authentication: Ensuring 401 status codes are returned when getBvbrcAuthToken returns undefined.
• Validation: Checking for 400 errors when required fields (like URLs or files in the upload route) are missing.
• Upstream Integration: Verifying that headers (like Authorization: OAuth <token>) are correctly passed to internal Shock or BV-BRC endpoints.

Sources: src/app/api/services/workspace/upload/tests/route.test.ts:71-110, src/app/api/services/workspace/upload/tests/route.test.ts:127-143

Rerun and Utility State Management

The rerun-utility is tested to ensure that job parameters from previous runs can be successfully re-hydrated into the application state.

Rerun Flow Logic

Feature	Validation Logic
Boolean Normalization	Converts 1, "true", and true to a unified boolean state.
Library Reconstruction	Rebuilds paired, single, and sra library objects from raw job parameters.
Service Mapping	Maps backend service IDs (e.g., Homology) to correct frontend routes (e.g., /services/blast).

Summary

The dxkb testing strategy relies on high coverage of data transformation logic and exhaustive mocking of external services. By isolating the UI, the service layer, and utility functions, the project ensures that regressions are caught early in the development lifecycle. The use of Vitest and MSW provides a fast and reliable environment for simulating complex bioinformatics workflows.

Sources: package.json:6-14, src/lib/tests/app-service.test.ts:1-10