Integration Tests

Relevant source files

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

• tests/integration/SqliteRepositoryTests.cpp
• tests/smoke/PresentationSmokeTest.cpp
• CMakeLists.txt
• AGENTS.md
• src/infra/sqlite/SqliteSsaRepository.cpp (Referenced via CMake)
• src/infra/preferences/JsonUserPreferencesStore.cpp (Referenced via integration tests)

Integration tests in the SSA Consulta Rapida C++ project are designed to validate the interaction between the software's core logic and its external infrastructure, specifically the SQLite database and the filesystem-based preference storage. These tests ensure that the data access layer correctly translates domain requests into SQL queries and that persistence mechanisms accurately maintain user state across sessions.

The testing strategy utilizes the Catch2 framework for core infrastructure and repository tests, while QtTest is employed for smoke tests that integrate the presentation layer with fake repository implementations. This approach validates the "contracts" between modules—such as the domain, infra, and presentation layers—without relying on manual UI interaction.
Sources: AGENTS.md:52-55, CMakeLists.txt:115-135

Database Integration

The primary focus of repository integration testing is the SqliteSsaRepository. These tests verify the repository's ability to execute complex queries involving pagination, text-based filtering, and the retrieval of distinct values for UI filters.

Test Fixture Lifecycle

To ensure test isolation, integration tests utilize a fixture creation process that generates a temporary SQLite database populated with a predefined schema and sample records. This process uses QTemporaryFile and the raw sqlite3 API to set up the environment before executing test cases.

The fixture includes a standard ssa_table containing columns such as numero_ssa, situacao, descricao_ssa, and various sector-related fields.
Sources: tests/integration/SqliteRepositoryTests.cpp:16-56

Validated Repository Behaviors

The integration tests cover several critical data access scenarios:

Test Scenario	Description	Key Validations
Pagination & Filtering	Applies a SsaPageRequest with search text.	Total row count accuracy and record matching.
Default Filtering	Checks exclusion logic for specific status codes.	Ensures 'SCA', 'SES', and 'STE' are filtered out by default.
Record Retrieval	Fetches a single record by its unique ID.	Validates mapping of SQL columns to SsaRecord values.
Distinct Values	Requests all unique values for a specific column.	Verifies the list of sector executors or statuses is populated.

Sources: tests/integration/SqliteRepositoryTests.cpp:61-94, src/domain/SsaTypes.h:118-123

User Preferences Integration

The JsonUserPreferencesStore is tested to ensure that application settings—such as themes, column visibility, and window layouts—are correctly serialized to and deserialized from the disk.

Persistence Verification

Tests validate the full lifecycle of user preferences, ensuring that a UserPreferencesSnapshot can be saved to a JSON file and reloaded without data loss or corruption.

Resilience and Defaults

Integration tests also verify the robustness of the preference system when encountering malformed data. For instance, if the visible_columns field in the JSON file contains invalid types, the system is expected to fall back to the ColumnCatalog::defaultVisibleKeys().
Sources: tests/integration/SqliteRepositoryTests.cpp:133-146

Presentation Smoke Tests

While not strictly "low-level" integration tests, the presentation smoke tests function as high-level integration points between the MainViewModel and the underlying services.

Architecture of Smoke Tests

These tests use "Fake" implementations of the repository and preference interfaces to simulate data flow while exercising the real logic of the ViewModels. This ensures that UI-driven actions (like clicking "Next Page" or changing a sort column) result in the correct state transitions and infrastructure calls.

Key Integrated Workflows

• Search and Apply: Verifies that setting search text and calling apply() updates the tableModel and status values.
• Sorting: Ensures that calling sortByColumn triggers a new request to the repository with the correct SortSpec.
• Pagination: Validates that nextPage() correctly increments the page index and updates the view.
• Preference Synchronization: Checks that changes to UI settings (like theme or density) immediately trigger an asynchronous save to the preference store.
  Sources: tests/smoke/PresentationSmokeTest.cpp:92-124, tests/smoke/PresentationSmokeTest.cpp:193-210

Execution and Validation

Integration tests are integrated into the CMake build system and are automatically discovered using catch_discover_tests.

Target Name	Test Framework	Purpose
ssa_integration_tests	Catch2	Validates ssa_infra (SQLite and JSON Store).
ssa_qt_presentation_tests	QtTest	Smoke tests for ssa_presentation logic.

Tests can be executed via the command line using:

ctest --preset dev --output-on-failure

Sources: CMakeLists.txt:127-135, AGENTS.md:58-61