tomevault-io TypeScript Testing Code Guide
Test File Structure
One-to-one matching with the file under test. Test files should be located in the same directory as the target file.
File Naming
Format: {target-file-name}.spec.ts.
Example: user.service.ts → user.service.spec.ts
Test Framework
Use Jest. Maintain consistency within the project.
Test Hierarchy
Organize by method (function) unit as major sections, and by test case as minor sections. Complex methods can have intermediate sections by scenario.
Test Coverage Selection
Omit obvious or overly simple logic (simple getters, constant returns). Prioritize testing business logic, conditional branches, and code with external dependencies.
Test Case Composition
At least one basic success case is required. Focus primarily on failure cases, boundary values, edge cases, and exception scenarios.
Test Independence
Each test should be executable independently. No test execution order dependencies. Initialize shared state for each test.
Given-When-Then Pattern
Structure test code in three stages—Given (setup), When (execution), Then (assertion). Separate stages with comments or blank lines for complex tests.
Test Data
Use hardcoded meaningful values. Avoid random data as it causes unreproducible failures. Fix seeds if necessary.
Mocking Principles
Mock external dependencies (API, DB, file system). For modules within the same project, prefer actual usage; mock only when complexity is high.
Test Reusability
Extract repeated mocking setups, fixtures, and helper functions into common utilities. Be careful not to harm test readability through excessive abstraction.
Integration/E2E Testing
Unit tests are the priority. Write integration/E2E tests when complex flows or multi-module interactions are difficult to understand from code alone. Place in separate directories (tests/integration, tests/e2e).
Test Naming
Test names should clearly express "what is being tested". Recommended format: "should do X when Y". Focus on behavior rather than implementation details.
Assertion Count
Multiple related assertions in one test are acceptable, but separate tests when validating different concepts.
Structure
Group methods/functionality with describe, write individual cases with it. Can classify scenarios with nested describe.
Mocking
Utilize Jest's jest.mock(), jest.spyOn(). Mock external modules at the top level; change behavior per test with mockReturnValue, mockImplementation.
Async Testing
Use async/await. Test Promise rejection with await expect(fn()).rejects.toThrow() form.
Setup/Teardown
Use beforeEach, afterEach for common setup/cleanup. Use beforeAll, afterAll only for heavy initialization (DB connection, etc.).
Type Safety
Type check test code too. Minimize as any or @ts-ignore. Use type guards or type assertions explicitly when needed.
Test Utils Location
For single-file use, place at bottom of same file. For multi-file sharing, use __tests__/utils or test-utils directory.
Coverage
Code coverage is a reference metric. Focus on meaningful test coverage rather than blindly pursuing 100%.
Converted and distributed by TomeVault — claim your Tome and manage your conversions.