avra-cadavra/.cursor/skills/test-implementation-requirements

Test Implementation Requirements

Core Principle

Tests must test real functionality. Mocks and stubs have strict limitations.

Mandatory Requirements

✅ REQUIRED

• Real Functionality - Tests exercise actual code paths and real dependencies
• Real Dependencies - Use actual services, repositories, and data sources
• Integration Testing - Prefer integration tests that test multiple components together
• Real Data - Use real data structures, real serialization, real validation

Mocks - Rare Cases Only

⚠️ Mocks require explicit approval and justification:

Before using any mock, you MUST:

1. Explain why a mock is necessary (what makes this a rare case)
2. Explain what real functionality would be tested if not for the mock
3. Get explicit user approval before implementing

Potentially acceptable rare cases:

• External APIs that charge per request
• Hardware dependencies that don't exist in test environment
• Time-dependent operations requiring specific timing control
• Network failures difficult to simulate with real dependencies

Even in rare cases: Prefer real implementations with test doubles (fake implementations) over mocks.

Stubs - Never Acceptable

❌ STUBS - FORBIDDEN:

• Stubs are FORBIDDEN in all cases
• Never use stubs as a replacement for real functionality
• Use real test implementations or get approval for mocks

Test Pattern Examples

✅ GOOD: Real Dependencies

test('repository fetches data from storage', () async {
  // Use real GetStorage (in-memory for tests)
  await TestStorageHelper.initTestStorage();
  final repository = MyRepositoryImpl();
  
  // Test with real implementation
  final result = await repository.getData();
  expect(result, isNotNull);
  
  // Cleanup
  await TestStorageHelper.clearTestStorage();
});

❌ BAD: Mock Dependencies

test('repository fetches data', () {
  // ❌ Mock without justification
  final mockDataSource = MockDataSource();
  final repository = MyRepositoryImpl(dataSource: mockDataSource);
  
  when(() => mockDataSource.getData()).thenReturn('test');
  // Tests mock, not real functionality
});

Checklist

• [ ] Tests use real functionality and real dependencies
• [ ] No stubs used anywhere
• [ ] If mocks are used, approval was obtained with explanation
• [ ] Mock usage is documented with justification
• [ ] Real behavior is tested, not just mocked behavior

Reference

• .cursorrules - Test Implementation Requirements section