__tests__

Integration tests that verify the example code works correctly and demonstrates proper API usage patterns. These tests catch breaking changes before users encou

Example Tests

Integration tests that verify the example code works correctly and demonstrates proper API usage patterns. These tests catch breaking changes before users encounter them.

Why Test Examples?

1. Examples stay working - Refactoring or API changes that break examples are caught immediately
2. Examples serve as integration tests - They test real usage patterns, not just isolated units
3. Documentation stays accurate - Examples are validated as correct usage patterns
4. User confidence - Users can trust that examples actually work

Test Structure

basic-usage.test.ts

Tests the basic usage examples:

• simple-geocoding.ts - Minimal setup without caching
• with-caching.ts - Cache performance demonstration
• batch-geocoding.ts - Processing multiple addresses

Verifies:

• Examples execute without errors
• Results have expected structure
• Cache behavior works as documented
• Error handling works correctly

custom-adapter.test.ts

Tests the custom adapter examples:

• fake-geocoding-service.ts - Creating test doubles
• redis-cache-example.ts - Implementing custom cache adapters

Verifies:

• Adapters implement the correct port interfaces
• Custom implementations work with use cases
• Examples demonstrate proper patterns

extracting-domain.test.ts

Tests the domain extraction examples:

• express-api-example.ts - Using domain in Express.js
• cli-tool-example.ts - Using domain in CLI tools

Verifies:

• Examples run without errors
• Documentation provides necessary information
• Examples mention key integration points

Running Tests

# Run all example tests
bun run test:examples

# Run specific test file
bun run test examples/__tests__/basic-usage.test.ts

# Run with coverage
bun run test --coverage examples/__tests__/

Writing New Example Tests

When adding a new example:

1. Create a test that verifies it runs without errors
2. Test the key functionality it demonstrates
3. Verify error handling if applicable
4. Keep tests focused on integration, not implementation details

Example pattern:

describe("New Example", () => {
  test("should demonstrate key feature", async () => {
    // Setup using same pattern as example
    const service = createFakeGeocodingService();
    const cache = createInMemoryCache();
    const useCase = createLookupAddressUseCase(service, cache);

    // Execute
    const result = await useCase.execute(address);

    // Verify key behavior
    expect(result).toBeDefined();
    expect(result.municipality.name).toBeDefined();
  });
});

Benefits

• Breaking change detection - API changes that break examples are caught in CI
• Living documentation - Examples are continuously validated
• User confidence - Users can trust examples actually work
• Integration testing - Tests real usage patterns across multiple modules
• Refactoring safety - Can refactor with confidence examples still work

CI Integration

These tests run as part of the standard test suite. Add to CI with:

- name: Test examples
  run: bun run test:examples