Backend Integration Testing

Relevant source files

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

• backend_starting_guide.md
• 2026-03-03-product-compare-backend-mvp-plan.md
• ARCHITECTURE.md
• README.md
• AGENTS.md

Backend integration testing in the ProductCompare project ensures that modular boundaries, database interactions, and transport layers function correctly as a unified system. The strategy focuses on verifying the "modular monolith" architecture, ensuring that context boundaries (such as Accounts, Catalog, and Specs) maintain their internal invariants while interacting with PostgreSQL and the GraphQL API layer.

The project utilizes a multi-layered testing approach, ranging from unit tests for pure logic to end-to-end integration tests for critical product flows. This infrastructure is supported by an Elixir/Phoenix stack using Ecto for database orchestration and Absinthe for GraphQL contract enforcement.
Sources: backend_starting_guide.md:144-152, 2026-03-03-product-compare-backend-mvp-plan.md:15-20

Testing Layers and Infrastructure

The testing strategy is divided into specific tiers to ensure comprehensive coverage across the backend's functional areas.

Core Testing Layers

Layer	Scope	Key Focus
Unit Tests	Pure Decision Logic	Validating stateless functions and data transformations.
Context Integration	DB + Boundary Behavior	Verifying Ecto repo operations, constraints, and context APIs.
GraphQL Resolver	Contract + Relay Shape	Ensuring schema compliance, Relay global ID handling, and pagination.
Channel Tests	Realtime Auth/Flow	Testing Phoenix Channels, presence, and message authorization.
End-to-End	Critical Product Flows	Full-system verification of high-value user journeys.

Sources: backend_starting_guide.md:146-152

Required Infrastructure

Testing relies on specialized case templates and patterns to manage state and isolation:

• DataCase: Utilizes the SQL sandbox owner pattern to ensure database isolation between concurrent test runs.
• ConnCase: Provides authentication helpers for testing web and API request flows.
• Fixtures: Modular domain fixtures located in test/support/fixtures provide deterministic data for tests.

Sources: backend_starting_guide.md:154-158

Integration Testing Workflows

The following diagram illustrates the integration flow between the GraphQL transport layer, the context boundaries, and the persistent storage.

The integration flow ensures that every request passes through transport validation, domain logic enforcement, and database constraints.
Sources: backend_starting_guide.md:112-130, 2026-03-03-product-compare-backend-mvp-plan.md:280-305

Convention-Specific Testing

A significant portion of integration testing is dedicated to enforcing the project's strict architectural conventions.

Identity and Token Lifecycle

Integration tests must verify the dual-ID strategy and secure token handling:

• ID Strategy: Tests confirm that relational tables correctly utilize a bigint primary key internally while exposing an entropy_id (UUIDv7) for external references.
• Token Security: Tests verify that raw secrets are never persisted and that authentication follows the SHA3-hash contract.
• Auth Semantics: Verification of token windows (e.g., 14-day session, 15-minute magic links) and explicit error states like :invalid_token or :expired_token.

Sources: backend_starting_guide.md:160-165, backend_starting_guide.md:73-89

GraphQL and Relay Compliance

The backend integration tests strictly enforce Relay modern standards:

• Global IDs: Tests ensure raw numeric IDs are rejected in favor of Relay Global IDs.
• Node Interface: Integration tests verify that the root node field correctly resolves various domain entities.
• Connections: Tests confirm that list surfaces provide deterministic sort orders and valid cursors for pagination.

Sources: backend_starting_guide.md:112-130, ARCHITECTURE.md:38-42

Domain-Specific Invariants

Critical workflows require specific integration assertions:

• Taxonomy: Verification of the taxon_closure table to ensure that tree traversals (ancestors/descendants) remain accurate after move_taxon operations.
• Specs/Claims: Testing the atomic replacement of "current" claims for a product attribute, ensuring transactional safety and uniqueness.
• Unit Conversion: Verifying base-unit normalization and dimension compatibility during claim submission.

Sources: 2026-03-03-product-compare-backend-mvp-plan.md:323-345, 2026-03-03-product-compare-backend-mvp-plan.md:145-165

CI Gates and Static Analysis

Backend integration is not only verified through runtime tests but also through mandatory static analysis and CI gates.

The CI pipeline serves as a hard gate, preventing code from being merged unless it satisfies compilation, testing, and type-safety requirements.
Sources: backend_starting_guide.md:168-177, README.md:41-45

Conclusion

Backend integration testing in ProductCompare is designed to protect the integrity of the modular monolith. By combining SQL-sandboxed integration tests, Relay-compliance checks, and strict static analysis gates, the system ensures that complex domain logic—such as taxonomy closures and spec claim lifecycles—remains robust as the project scales.
Sources: backend_starting_guide.md:144-152, 2026-03-03-product-compare-backend-mvp-plan.md:350-360