Testing Documentation#

This document outlines the testing patterns and practices used in the noteleaf application.

Overview#

The codebase follows Go's standard testing practices with specialized testing utilities for complex scenarios. Tests use the standard library along with carefully selected dependencies like faker for data generation and BubbleTea for TUI testing. This approach keeps dependencies minimal while providing robust testing infrastructure for interactive components and complex integrations.

Organization#

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. The codebase includes four main test utility files that provide specialized testing infrastructure:

internal/services/test_utilities.go - HTTP mocking and media service testing
internal/repo/test_utilities.go - Database testing and data generation
internal/ui/test_utilities.go - TUI testing framework and interactive component testing
internal/handlers/test_utilities.go - Handler testing with database isolation and input simulation

Patterns#

Handler Creation#

Tests 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.

Database Isolation#

Tests 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.

The 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.

Resource Management#

Tests 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.

Error Handling#

Tests 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.

Context Cancellation#

Error case testing frequently uses context cancellation to simulate database and network failures. The pattern creates a context, immediately cancels it, then calls the function under test to verify error handling. This provides a reliable way to test error paths without requiring complex mock setups or external failure injection.

Command Structure#

Command 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.

Interface Compliance#

Tests verify interface compliance using compile-time checks with blank identifier assignments. This ensures structs implement expected interfaces without runtime overhead.

Test Infrastructure#

Test Utility Frameworks#

The codebase provides comprehensive testing utilities organized by layer and functionality. Each test utility file contains specialized helpers, mocks, and test infrastructure for its respective domain.

Database Testing Utilities#

internal/repo/test_utilities.go provides comprehensive database testing infrastructure:

In-Memory Database Creation: CreateTestDB creates isolated SQLite databases with full schema
Sample Data Factories: Functions like CreateSampleTask, CreateSampleBook generate realistic test data
Faker Integration: Uses jaswdr/faker for generating realistic fake data with CreateFakeArticle
Test Setup Helpers: SetupTestData creates a full set of sample data across all models
Custom Assertions: Generic assertion helpers like AssertEqual, AssertContains, AssertNoError

HTTP Service Testing#

internal/services/test_utilities.go provides HTTP mocking and media service testing:

Mock Configuration: MockConfig structure for configuring service behavior
Function Replacement: SetupMediaMocks replaces service functions with controllable mocks
Sample Data Access: Helper functions that use embedded HTML samples for realistic testing
Specialized Scenarios: Pre-configured mock setups for success and failure scenarios
Assertion Helpers: Domain-specific assertions for movies, TV shows, and error conditions

TUI Testing Framework#

internal/ui/test_utilities.go provides a comprehensive BubbleTea testing framework:

TUITestSuite: Complete testing infrastructure for interactive TUI components
Controlled I/O: ControlledOutput and ControlledInput for deterministic testing
Message Simulation: Key press simulation, message queuing, and timing control
State Verification: Model state checking and view content assertions
Timeout Handling: Configurable timeouts for async operations
Mock Repository: Test doubles for repository interfaces

Handler Testing Infrastructure#

internal/handlers/test_utilities.go provides end-to-end handler testing:

Environment Isolation: HandlerTestHelper creates isolated test environments
Input Simulation: InputSimulator for testing interactive components that use fmt.Scanf
HTTP Mocking: Comprehensive HTTP server mocking for external API testing
Database Helpers: Database corruption and error scenario testing
Editor Mocking: MockEditor for testing file editing workflows
Assertion Helpers: Handler-specific assertions and verification functions

Advanced Testing Patterns#

Input Simulation for Interactive Components#

Interactive handlers that use fmt.Scanf require special testing infrastructure with an io.Reader implementation.

The InputSimulator provides controlled input sequences that prevent tests from hanging while maintaining coverage of interactive code paths.

TUI Testing with BubbleTea Framework#

The TUI testing framework addresses the fundamental challenge of testing interactive terminal applications in a deterministic, concurrent environment. BubbleTea's message-passing architecture creates unique testing requirements that standard Go testing patterns cannot adequately address.

The framework implements a controlled execution environment that replaces BubbleTea's typical program loop with a deterministic testing harness. Rather than running an actual terminal program, the "testing suite" directly manages model state transitions by simulating the Update/View cycle. This approach eliminates the non-deterministic behavior inherent in real terminal interactions while preserving the exact message flow patterns that production code experiences.

State verification relies on function composition patterns where test conditions are expressed as closures that capture specific model states. The WaitFor mechanism uses polling with configurable timeouts, addressing the async nature of BubbleTea model updates without creating race conditions. This pattern bridges imperative test assertions with BubbleTea's declarative update model. This is inspired by front-end/TS/JS testing patterns.

The framework's I/O abstraction layer replaces terminal input/output with controlled buffers that implement standard Go interfaces. This design maintains interface compatibility while providing complete control over timing and content. The controlled I/O system captures all output for later verification and injects precise input sequences, enabling complex interaction testing without external dependencies.

Concurrency management uses channels and context propagation to coordinate between the testing framework and the model under test. The suite manages goroutine lifecycle and ensures proper cleanup, preventing test interference and resource leaks. This architecture supports testing of models that perform background operations or handle async events.

HTTP Service Mocking#

Service testing uses HTTP mocking with request capture. A MockServer is instantiated, and its URL is used in test scoped services.

Database Schema Testing#

Database tests use comprehensive schema setup with (automatic) cleanup

Environment Manipulation#

Environment testing utilities provide controlled environment manipulation. Environment variables are restored after instantiation.

Test Organization Patterns#

Single Root Test#

The 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. This pattern offers several advantages: clear test hierarchy with logical grouping, ability to run specific test sections, consistent test structure across the codebase, and shared setup that can be inherited by subtests.

Integration vs Unit Testing#

The codebase emphasizes integration testing over heavy mocking by using real handlers and services to verify actual behavior rather than mocked interactions. The goal is to catch integration issues while maintaining test reliability.

Static Output#

UI 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.

Standard Output Redirection#

For testing functions that write to stdout, tests use a pipe redirection pattern with goroutines to capture output. The pattern saves the original stdout, redirects to a pipe, captures output in a separate goroutine, and restores stdout after the test. This ensures clean output capture without interfering with the testing framework.

Utilities#

Test Data Generation#

The codebase uses sophisticated data generation strategies:

Factory Functions: Each package provides factory functions for creating valid test data
Faker Integration: Uses jaswdr/faker for generating realistic fake data with proper randomization
Sample Data Creators: Functions like CreateSampleTask, CreateSampleBook provide consistent test data
Embedded Resources: Services use embedded HTML samples from real API responses for realistic testing

Assertion Helpers#

Custom assertion functions provide clear error messages and reduce test code duplication:

Generic Assertions: AssertEqual, AssertNoError, AssertContains for common checks
Domain-Specific Assertions: AssertMovieInResults, AssertNoteExists for specialized verification
TUI Assertions: AssertViewContains, AssertModelState for BubbleTea model testing
HTTP Assertions: AssertRequestMade for verifying HTTP interactions

Mock Infrastructure#

Each layer provides specialized mocking capabilities:

Service Mocking: Function replacement with configurable behavior and embedded test data
HTTP Mocking: HTTPMockServer with request capture and response customization
Input Mocking: InputSimulator for deterministic interactive component testing
Editor Mocking: MockEditor for file editing workflow testing
Repository Mocking: MockTaskRepository for TUI component testing

Environment and Resource Management#

Testing utilities provide comprehensive resource management:

Environment Isolation: EnvironmentTestHelper for controlled environment variable manipulation
Database Isolation: Temporary SQLite databases with automatic cleanup
File System Isolation: Temporary directories with automatic cleanup
Process Isolation: Handler helpers that create completely isolated test environments

Testing CLI Commands#

Command 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.

CommandGroup Interface Testing#

The 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.

Interface compliance is tested using compile-time checks within the "Interface Implementations" subtest, ensuring all command structs properly implement the CommandGroup interface without runtime overhead.

Performance Considerations#

Tests 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.

The single root test pattern allows for efficient resource management where setup costs can be amortized across multiple related test cases.

Interactive Component Testing#

The codebase provides comprehensive testing infrastructure for interactive components, including both terminal UI applications and command-line interfaces that require user input.

Input Simulation Framework#

Interactive handlers that use fmt.Scanf require specialized testing infrastructure:

InputSimulator: Provides controlled input sequences that implement io.Reader
Menu Selection Helpers: MenuSelection, MenuCancel, MenuSequence for common interaction patterns
Handler Integration: Handlers can accept io.Reader for input, enabling deterministic testing
Cleanup Management: Automatic cleanup prevents resource leaks in test environments

TUI Testing with BubbleTea#

The TUI testing framework provides complete testing infrastructure for interactive terminal interfaces:

TUITestSuite: Comprehensive testing framework for BubbleTea models
Message Simulation: Key press simulation, window resize events, and custom message handling
State Verification: Model state checking with custom condition functions
View Assertions: Content verification and output capture
Timing Control: Configurable timeouts and delay handling for async operations
Mock Integration: Repository mocking for isolated component testing

Interactive Test Scenarios#

Interactive handlers should test comprehensive scenarios:

Valid user selections - User chooses valid menu options and inputs
Cancellation flows - User chooses to cancel operations (option 0 or escape keys)
Invalid choices - User selects out-of-range options or provides invalid input
Navigation patterns - Keyboard navigation, scrolling, and multi-step interactions
Error handling - Network errors, service failures, and data validation errors
Empty states - Search returns no results, empty lists, and missing data
Edge cases - Boundary conditions, malformed input, and resource constraints

TUI Component Testing Patterns#

BubbleTea components use specialized testing patterns:

Key Sequence Testing: Simulate complex user interactions with timing
State Transition Testing: Verify model state changes through user actions
View Content Testing: Assert specific content appears in rendered output
Async Operation Testing: Handle loading states and network operations
Responsive Design Testing: Test different terminal sizes and window resize handling

This comprehensive testing approach ensures interactive components work reliably in automated environments while maintaining full coverage of user interaction paths.

Errors#

Error coverage follows a systematic approach to identify and test failure scenarios:

Context Cancellation - Primary method for testing database and network timeout scenarios
Invalid Input - Malformed data, empty inputs, boundary conditions
Resource Exhaustion - Database connection failures, memory limits
Constraint Violations - Duplicate keys, foreign key failures
State Validation - Testing functions with invalid system states
Interactive Input - Invalid user choices, cancellation handling, input simulation errors