testing

Dart & Flutter Testing

VGV testing conventions for Dart and Flutter. The framework APIs are assumed; what follows is the house style layered on top of them.

Core Standards

Apply these standards to all test work:

• Descriptive test names — verbose, readable names that describe the behavior; never 'works' or 'renders'
• Hierarchical group/test structure that reads as natural sentences — top-level group for the class, nested group for the method, test for the behavior (e.g., UserRepository → getUser → returns User when API succeeds)
• String interpolation for type references — use 'returns $User' not 'returns User' so renames propagate automatically
• Private mocks per file — declare class _MockX extends Mock implements X {} with underscore prefix to prevent cross-file coupling
• Contained test setup within groups — all setUp/tearDown calls live inside a group, never at the top level of main()
• Initialize mutable objects in setUp() with late — declare late MyDep dep; then assign in setUp so each test gets a fresh instance
• No shared mutable state between tests — never use static members, global variables, or top-level final instances that persist across tests
• Use package:mocktail — never package:mockito
• Constant test tags — use an abstract class TestTag with static const fields; never pass raw string literals as tags
• Test behavior, not properties — widget tests focus on functional outcomes; static visual properties validated via golden tests
• Use pumpApp test helper — wrap widgets via shared helper in test/helpers/pump_app.dart; never inline pumpWidget(MaterialApp(...))
• Tag all golden tests — annotate with TestTag.golden so goldens can run/update independently
• Pass directory to the test MCP tool when the project is not at the workspace root — monorepos with the Flutter project in a subdirectory (e.g. mobile/) require directory: 'mobile'; omit it only when pubspec.yaml is at the workspace root
• Pass timeout_seconds to the test MCP tool — Flutter tests can hang indefinitely when pumpAndSettle() is called without a timeout; set a cap (e.g. timeout_seconds: 120) so the run is killed instead of stalling
• Cross-harness fallback for the test MCP tool — on Claude Code use mcp__very-good-cli__test; on a host without this plugin's Bash hooks and without that MCP server connected, run very_good test (or flutter test / dart test) directly with the same coverage and timeout options — never block on a missing MCP server