Testing Strategy
Relevant source files
The following files were used as context for generating this wiki page:
The testing strategy for Better Tables is designed to ensure stability, performance, and type safety across a modular monorepo. It employs a multi-tiered approach ranging from low-level unit tests and type-conformance checks to high-level integration and End-to-End (E2E) performance monitoring. The strategy emphasizes deterministic verification, such as exact operation counting and type instantiation budgets, to prevent regressions in core product pillars like developer experience and runtime performance.
Central to this strategy is the use of automated gates within the CI/CD pipeline, ensuring that every package—including core logic, adapters, and UI components—is verified through type-checking, linting, and functional testing before deployment.
Sources: plans/001-ci-verification-baseline.md:1-10, plans/063-performance-test-harness.md:15-25
Core Verification Tiers
The project categorizes testing into four distinct tiers, each serving a specific role in the quality assurance lifecycle.
Tier 1: Interaction & Query Cost Gates
These tests are blocking and run on every Pull Request. They do not rely on wall-clock timing but instead assert exact integers for operations. This includes counting database fetches, facet requests, and React component commits.
- Target: Prevention of N+1 queries, duplicate fetches, and cache bypasses.
- Tools: Counting stub adapters, Drizzle
Logger.logQuery, and local render counters.
Tier 2: Growth-Ratio Gates
These tests monitor the scalability of core algorithms by comparing operations at different data scales (e.g., 1k vs. 10k rows). Instead of absolute time, they assert ratio bounds to remain machine-independent.
- Target: Identifying accidental $O(n^2)$ complexity in data transformers or filter application.
Tier 3: Micro-benchmarks
Non-blocking benchmarks that track performance trends over time. These are used for core managers, URL codecs, and SQL generation logic.
- Tools:
mitatasuites under the Bun runtime.
Tier 4: E2E Interaction Latency
High-level tests measuring felt latency for user interactions like pagination or filter changes.
- Tools: Playwright measuring
click-to-next-paintandclick-to-rows-updated.
Sources: plans/063-performance-test-harness.md:85-115, plans/043-integration-e2e-harness.md:65-75
Continuous Integration (CI) Pipeline
The CI pipeline, defined in .github/workflows/test.yml, acts as the primary gatekeeper for code quality. It is configured to trigger on changes to any package within the packages/ or apps/ directories.
Figure 1: The CI workflow executes static analysis followed by parallelized package-specific test suites.
Sources: plans/001-ci-verification-baseline.md:65-105, plans/033-verification-infra-truth.md:95-105
Specialized Testing Areas
Type Performance Gating
Better Tables utilizes a unique "Type-perf gate" to prevent the TypeScript compiler from becoming a bottleneck during development. This involves measuring Instantiations and Check time for complex generic types.
- Budget: $\leq 2,000,000$ instantiations per fixture.
- Verification:
tsc --noEmit --extendedDiagnosticsparsed by automated test scripts.
Integration Testing with Real Adapters
To validate the full flow from column definitions to SQL execution and UI rendering, integration tests utilize a bun:sqlite backed Drizzle adapter with seed data.
- Scope: Verifying that initial renders show seeded rows and that filter application triggers correct refetches and formatting.
Sources: plans/063-performance-test-harness.md:185-200, plans/043-integration-e2e-harness.md:80-90
Testing Infrastructure Summary
| Feature | Description | Relevant Files |
|---|---|---|
| Monorepo Task Runner | Turbo handles caching and task execution. | turbo.json |
| Static Analysis | Biome for linting and formatting; TSC for type safety. | biome.json, tsconfig.json |
| Runtime Environment | Bun 1.3.1 is the pinned runtime for CI and local execution. | package.json |
| Test Locations | Centralized in tests/ directories within each package. | packages/*/tests/ |
| Database Fixtures | Deterministic SQLite seeds for integration/adapter tests. | packages/adapters/drizzle/tests/ |
Sources: CLAUDE.md:20-55, plans/033-verification-infra-truth.md:40-55, plans/README.md:155-165
Summary
The Better Tables testing strategy shifts verification as far left as possible by combining rigorous static analysis with deterministic runtime operation counting. By strictly monitoring type instantiation budgets and operation ratios, the project maintains its commitment to high-performance data handling and superior developer experience, ensuring that internal architectural changes do not degrade the user-facing product.
Sources: plans/063-performance-test-harness.md:235-245, plans/README.md:10-25