Testing

This guide outlines our approach to testing across the codebase. These guidelines are language-agnostic and focus on principles and practices that ensure our tests are maintainable, reliable, and effective at preventing regressions.

Where Tests Live

Following our feature-based organization, tests should live next to their features following the colocation pattern.

Colocation Pattern

Place test files next to the code they test. Use the standard naming convention for your language:

• TypeScript/JavaScript: <file>.test.ts
• Python: <file>_test.py

• Directoryfeatures/

  • Directoryupload/

    • uploadService.ts
    • uploadService.test.ts
  • Directorypresentation/

    • parser.py
    • parser_test.py

Alternative: Feature-Level Test Directory

For larger features with multiple related files, you may use a tests/ directory within the feature folder:

• Directoryfeatures/

  • Directorypresentation/

    • parser.py
    • serializer.py
    • Directorytests/

      • parser_test.py
      • serializer_test.py
      • integration_test.py

Small Files, Small Tests

When possible, keep source files small and focused. This naturally leads to smaller, more manageable test files that test a single module or component. Small files are easier to understand, test, and maintain.

Bug Duty: Regression Prevention

During bug duty, when fixing a bug, one should ideally follow this workflow:

1. Write a failing test that reproduces the bug
2. Fix the bug so the test passes
3. Refactor if needed, keeping the test passing

This ensures the bug is documented and won’t return unnoticed.