Unit Testing Strategy (Catch2)

Relevant source files

The following files were used as context for generating this wiki page:

• tests/unit/DomainTests.cpp
• tests/unit/SearchParserTests.cpp
• tests/unit/SqlQueryBuilderTests.cpp
• tests/integration/SqliteRepositoryTests.cpp
• tests/smoke/PresentationSmokeTest.cpp
• CMakeLists.txt
• AGENTS.md

The unit testing strategy for the SSA Consulta Rapida Cpp project is centered around the Catch2 framework for core, query, and infrastructure components. This strategy ensures functional correctness by validating domain rules, search parsing logic, and SQL query generation in isolation, while also extending to integration tests for persistence layers.

The project follows a modular architecture where tests are categorized into unit, integration, and smoke tests. Unit tests specifically target the ssa_core library, focusing on the absence of external dependencies like Qt or SQLite to ensure fast and deterministic execution.

Sources: AGENTS.md:46-49, CMakeLists.txt:115-125

Test Architecture and Organization

The testing infrastructure is integrated into the CMake build system, conditioned by the SSA_BUILD_TESTS option. The project organizes tests into three distinct executables to separate concerns and execution environments.

Core Unit Testing (ssa_core_tests)

The core unit tests validate the foundational logic of the application without requiring a database or GUI.

• Domain Validation: Ensures that the ColumnCatalog correctly exposes visible columns and search keys, and that domain objects like SsaRecord handle missing values gracefully.
  • Sources: tests/unit/DomainTests.cpp:6-24
• Search Parser Logic: Verifies the SearchParser capability to handle complex input strings, including comma-separated terms (implicit AND), negation (!), and various match modes like starts-with (^), ends-with ($), equals (=), and regex (~).
  • Sources: tests/unit/SearchParserTests.cpp:5-23
• SQL Builder Integrity: Validates that the SqlQueryBuilder produces correct SQL syntax, properly uses bound parameters to prevent injection, and correctly maps application filters to SQL constructs like REGEXP or LIKE.
  • Sources: tests/unit/SqlQueryBuilderTests.cpp:5-29

Integration Testing (ssa_integration_tests)

Integration tests use Catch2 to verify the interaction between the infrastructure layer and the SQLite database. These tests utilize QTemporaryFile and QTemporaryDir to create isolated environments (fixtures) for each test run.

Key Testing Components

Component	Test File	Responsibility
Domain Logic	DomainTests.cpp	Validates ColumnCatalog contracts and SsaRecord value retrieval.
Search Parsing	SearchParserTests.cpp	Tests string-to-token conversion for filtering expressions.
Query Building	SqlQueryBuilderTests.cpp	Ensures SQL generation uses bound parameters and rejects invalid columns.
Infrastructure	SqliteRepositoryTests.cpp	Verifies paging, filtering, and record retrieval against real SQLite files.
Preferences	SqliteRepositoryTests.cpp	Validates JSON serialization/deserialization of user preferences.

Sources: tests/unit/DomainTests.cpp, tests/unit/SearchParserTests.cpp, tests/unit/SqlQueryBuilderTests.cpp, tests/integration/SqliteRepositoryTests.cpp

Preference Store Validation

A critical part of the strategy involves testing the JsonUserPreferencesStore. This ensures that user settings—such as page size, theme, visible columns, and column widths—are correctly persisted and that the system can recover from corrupted or invalid JSON files by falling back to defaults.

Sources: tests/integration/SqliteRepositoryTests.cpp:103-145

Smoke Testing (QtTest)

While Catch2 handles the core logic, presentation-layer testing is performed via PresentationSmokeTest.cpp using Qt6::Test. This suite uses Fakes (e.g., FakeRepository, FakePreferences) to simulate the underlying layers, allowing for the validation of MainViewModel behavior, signal-slot connections, and asynchronous request handling.

Summary

The unit testing strategy provides a robust safety net by combining Catch2 for deep logic verification and QtTest for UI state coordination. By enforcing a strict separation between the core domain and the Qt/SQLite infrastructure, the project achieves a high level of testability, allowing for rapid validation of query compilation, domain constraints, and user preference persistence.

Sources: AGENTS.md:5-15, AGENTS.md:46-49