cli + tui to publish to leaflet (wip) & manage tasks, notes & watch/read lists 馃崈
charm
leaflet
readability
golang
1# Testing Documentation
2
3This document outlines the testing patterns and practices used in the noteleaf application.
4
5## Testing Principles
6
7The codebase follows Go's standard testing practices without external libraries. Tests use only the standard library `testing` package and avoid mock frameworks or assertion libraries. This keeps dependencies minimal and tests readable using standard Go patterns.
8
9## Test File Organization
10
11Test files follow the standard Go convention of `*_test.go` naming. Each package contains its own test files alongside the source code. Test files are organized by functionality and mirror the structure of the source code they test.
12
13## Testing Patterns
14
15### Handler Creation Pattern
16
17Tests create real handler instances using temporary databases to ensure test isolation. Factory functions handle both database setup and handler initialization, returning both the handler and a cleanup function.
18
19### Database Isolation
20
21Tests use temporary directories and environment variable manipulation to create isolated database instances. Each test gets its own temporary SQLite database that is automatically cleaned up after the test completes.
22
23The `setupCommandTest` function creates a temporary directory, sets `XDG_CONFIG_HOME` to point to it, and initializes the database schema. This ensures tests don't interfere with each other or with development data.
24
25### Resource Management
26
27Tests properly manage resources using cleanup functions returned by factory methods. The cleanup function handles both handler closure and temporary directory removal. This pattern ensures complete resource cleanup even if tests fail.
28
29### Error Handling
30
31Tests use `t.Fatal` for setup errors that prevent test execution and `t.Error` for test assertion failures. Fatal errors stop test execution while errors allow tests to continue checking other conditions.
32
33### Command Structure Testing
34
35Command group tests verify cobra command structure including use strings, aliases, short descriptions, and subcommand presence. Tests check that commands are properly configured without executing their logic.
36
37### Interface Compliance Testing
38
39Tests verify interface compliance using compile-time checks with blank identifier assignments. This ensures structs implement expected interfaces without runtime overhead.
40
41```go
42var _ CommandGroup = NewTaskCommands(handler)
43```
44
45## Test Organization Patterns
46
47### Single Root Test Pattern
48
49The preferred test organization pattern uses a single root test function with nested subtests using `t.Run`. This provides clear hierarchical organization and allows running specific test sections while maintaining shared setup and context.
50
51```go
52func TestCommandGroup(t *testing.T) {
53 t.Run("Interface Implementations", func(t *testing.T) {
54 // Test interface compliance
55 })
56
57 t.Run("Create", func(t *testing.T) {
58 t.Run("TaskCommand", func(t *testing.T) {
59 // Test task command creation
60 })
61 t.Run("MovieCommand", func(t *testing.T) {
62 // Test movie command creation
63 })
64 })
65}
66```
67
68This pattern offers several advantages: clear test hierarchy with logical grouping, ability to run specific test sections with `go test -run TestCommandGroup/Create/TaskCommand`, consistent test structure across the codebase, and shared setup that can be inherited by subtests.
69
70### Integration vs Unit Testing
71
72The codebase emphasizes integration testing over heavy mocking. Tests use real handlers and services to verify actual behavior rather than mocked interactions. This approach catches integration issues while maintaining test reliability.
73
74### Static Output Testing
75
76UI components support static output modes for testing. Tests capture output using bytes.Buffer and verify content using string contains checks rather than exact string matching for better test maintainability.
77
78## Test Utilities
79
80### Helper Functions
81
82Test files include helper functions for creating test data and finding elements in collections. These utilities reduce code duplication and improve test readability.
83
84### Mock Data Creation
85
86Tests create realistic mock data using factory functions that return properly initialized structs with sensible defaults. This approach provides consistent test data across different test cases.
87
88## Testing CLI Commands
89
90Command group tests focus on structure verification rather than execution testing. Tests check command configuration, subcommand presence, and interface compliance. This approach ensures command trees are properly constructed without requiring complex execution mocking.
91
92### CommandGroup Interface Testing
93
94The CommandGroup interface enables testable CLI architecture. Tests verify that command groups implement the interface correctly and return properly configured cobra commands. This pattern separates command structure from command execution.
95
96Interface compliance is tested using compile-time checks within the "Interface Implementations" subtest, ensuring all command structs properly implement the CommandGroup interface without runtime overhead.
97
98## Performance Considerations
99
100Tests avoid expensive operations in setup functions. Handler creation uses real instances but tests focus on structure verification rather than full execution paths. This keeps test suites fast while maintaining coverage of critical functionality.
101
102The single root test pattern allows for efficient resource management where setup costs can be amortized across multiple related test cases.
103
104## Best Practices Summary
105
106Use factory functions for test handler creation with proper cleanup patterns. Organize tests using single root test functions with nested subtests for clear hierarchy. Manage resources with cleanup functions returned by factory methods. Prefer integration testing over mocking for real-world behavior validation. Verify interface compliance at compile time within dedicated subtests. Focus command tests on structure verification rather than execution testing. Leverage the single root test pattern for logical grouping and selective test execution. Use realistic test data with factory functions for consistent test scenarios.