testing-standards

name	testing-standards
description	Standards and instructions for testing in the Nothingness project.

Testing Standards

Organization

We mirror the lib/ directory structure within test/ to ensure tests are easy to locate.

• test/models/ -> Unit tests for data models.
• test/services/ -> Unit tests for services (mock dependencies).
• test/widgets/ -> Widget tests for reusable components.
• test/screens/ -> Widget tests for full pages.

The debug/automation harness lives out of tree under dev/ (e.g. dev/test_harness.dart, dev/fake_audio_transport.dart); production reaches it only through the thin lib/debug_hooks.dart seam.

We also use Flutter's emulator/device integration tests:

• integration_test/ -> End-to-end behavior tests on a real device/emulator.

Requirement

• All new logic (models, services) must have unit tests.
• All new UI components (widgets, screens) must have widget tests.
• Behavior that depends on platform/device eventing (e.g. "natural track ended", lifecycle, real navigation flows) should have integration_test coverage.
• No Placeholders: Do not commit empty test files or placeholder tests (e.g., expect(true, isTrue)). If a component cannot be tested yet, document the reason in the code or a tracking issue, but do not create a dummy test file.

Integration tests (emulator/device)

Use integration_test/ when validating cross-widget behavior or contracts that are hard to express in pure widget tests:

• Skip/advance behavior across tap/next/prev/end events
• "Inspectable" diagnostics flows and stable UI selectors

Test-only entrypoint

When integration tests need deterministic behavior (no real audio files, no plugin-level playback), use the out-of-tree test-only entrypoint:

• dev/main_test.dart

This can wire:

• a fake transport
• controllable file-exists provider
• stable selectors (e.g. ValueKeys) for automation

How to Add Tests

1. Create File: Create a test file in the corresponding test/ subdirectory (e.g., lib/models/foo.dart -> test/models/foo_test.dart).
2. Mocking: Use mockito for external dependencies.
   • Add @GenerateMocks([DependencyClass]) to your test entry point if needed.
   • Run dart run build_runner build to generate mocks.
3. Widget Tests: Use testWidgets and pumpWidget. Ensure you wrap widgets in MaterialApp if they depend on theme/navigation.

How to Run Tests

• All Tests: flutter test
• Specific File: flutter test test/path/to/file_test.dart
• Integration tests (single file): flutter test -d <deviceId> integration_test/some_test.dart