@@ -11,26 +11,31 @@ Property-based testing (PBT) uses randomly generated inputs to verify that syste
1111### Core Components
1212
1313#### 1. ** Generators** (` generators/ ` )
14+
1415- ** ` schema-generator.ts ` ** : Generates random database schemas with tables, columns, and relationships
1516- ** ` row-generator.ts ` ** : Creates test data that conforms to the generated schemas
1617- ** ` query-generator.ts ` ** : Generates random SQL queries using TanStack DB's query builder
1718- ** ` mutation-generator.ts ` ** : Creates random insert, update, and delete operations
1819
1920#### 2. ** SQL Translation** (` sql/ ` )
21+
2022- ** ` ast-to-sql.ts ` ** : Converts TanStack DB's Intermediate Representation (IR) to SQLite SQL
2123- ** ` sqlite-oracle.ts ` ** : Provides a real SQLite database instance for comparison
2224
2325#### 3. ** Test Harness** (` harness/ ` )
26+
2427- ** ` property-test-harness.ts ` ** : Main orchestrator that runs test sequences and validates properties
2528
2629#### 4. ** Utilities** (` utils/ ` )
30+
2731- ** ` incremental-checker.ts ` ** : Validates invariants and compares TanStack DB vs SQLite results
2832- ** ` normalizer.ts ` ** : Normalizes data for comparison (handles type differences, ordering, etc.)
2933- ** ` functional-to-structural.ts ` ** : Converts functional expressions to structural IR
3034
3135### Test Types
3236
3337#### 1. ** Property-Based Tests** (` property-based-tests.test.ts ` )
38+
3439Tests the core properties that must hold true for the query engine:
3540
3641- ** Property 1: Snapshot Equality** : TanStack DB results match SQLite oracle
@@ -42,6 +47,7 @@ Tests the core properties that must hold true for the query engine:
4247- ** Property 7: Error Handling** : Edge cases are handled gracefully
4348
4449#### 2. ** Quick Test Suite** (` quick-test-suite.test.ts ` )
50+
4551Rapid validation tests for the PBT framework itself:
4652
4753- Schema generation validation
@@ -51,6 +57,7 @@ Rapid validation tests for the PBT framework itself:
5157- Basic property validation
5258
5359#### 3. ** Comprehensive SQL Coverage** (` comprehensive-sql-coverage.test.ts ` )
60+
5461Systematic testing of SQL translation capabilities:
5562
5663- All comparison operators (` eq ` , ` gt ` , ` gte ` , ` lt ` , ` lte ` , ` in ` , ` like ` , ` ilike ` )
@@ -62,6 +69,7 @@ Systematic testing of SQL translation capabilities:
6269- ` ORDER BY ` , ` GROUP BY ` , ` LIMIT ` , ` OFFSET `
6370
6471#### 4. ** Framework Unit Tests** (` framework-unit-tests.test.ts ` )
72+
6573Unit tests for individual PBT components:
6674
6775- Generator validation
@@ -70,13 +78,15 @@ Unit tests for individual PBT components:
7078- Oracle validation
7179
7280#### 5. ** Integration Tests**
81+
7382- ** ` tanstack-sqlite-comparison.test.ts ` ** : Direct comparison of TanStack DB vs SQLite
7483- ** ` query-builder-ir-extraction.test.ts ` ** : Tests IR extraction from query builder
7584- ** ` ir-to-sql-translation.test.ts ` ** : Tests IR to SQL translation
7685
7786## How It Works
7887
7988### 1. ** Test Sequence Generation**
89+
8090``` typescript
8191// Generate a random schema
8292const schema = generateSchema (config )
@@ -89,6 +99,7 @@ const commands = generateCompleteTestSequence(schema, config)
8999```
90100
91101### 2. ** Test Execution**
102+
92103``` typescript
93104// Initialize test state
94105const state = {
@@ -106,6 +117,7 @@ for (const command of commands) {
106117```
107118
108119### 3. ** Property Validation**
120+
109121``` typescript
110122// Check snapshot equality
111123const snapshotCheck = await checker .checkSnapshotEquality ()
@@ -121,6 +133,7 @@ const rowCountCheck = await checker.checkRowCountSanity()
121133```
122134
123135### 4. ** Result Comparison**
136+
124137``` typescript
125138// Compare TanStack DB vs SQLite results
126139const comparison = normalizer .compareRowSets (tanstackResult , sqliteResult )
@@ -132,7 +145,8 @@ if (hasOrderBy) {
132145} else {
133146 // Results can be in different order
134147 const sortedComparison = normalizer .compareRowSets (
135- sortedTanstack , sortedSqlite
148+ sortedTanstack ,
149+ sortedSqlite
136150 )
137151 expect (sortedComparison .equal ).toBe (true )
138152}
@@ -141,52 +155,64 @@ if (hasOrderBy) {
141155## Key Features
142156
143157### ** Real SQLite Oracle**
158+
144159Uses ` better-sqlite3 ` for deterministic comparison against TanStack DB's results.
145160
146161### ** Comprehensive SQL Translation**
162+
147163Converts TanStack DB's IR to SQLite-compatible SQL, supporting:
164+
148165- All comparison operators
149166- Logical operators
150167- Functions and aggregates
151168- Subqueries and joins
152169- Ordering and grouping
153170
154171### ** Robust Data Normalization**
172+
155173Handles type differences, ordering, and edge cases:
174+
156175- Number precision differences
157176- Boolean vs integer representations
158177- Object/array serialization
159178- Null handling
160179
161180### ** Error Handling**
181+
162182Gracefully handles expected failures:
183+
163184- Non-existent rows/columns
164185- Invalid SQL syntax
165186- Schema generation edge cases
166187
167188### ** Reproducibility**
189+
168190- Deterministic seeds for reproducible failures
169191- Detailed error reporting with failing command sequences
170192- Regression test fixtures
171193
172194## Running Tests
173195
174196### Quick Tests
197+
175198``` bash
176199pnpm test:property:quick
177200```
178201
179202### Full Property Tests
203+
180204``` bash
181205pnpm test:property
182206```
183207
184208### Coverage Report
209+
185210``` bash
186211pnpm test:property:coverage
187212```
188213
189214### Example Usage
215+
190216``` bash
191217pnpm test:property:example
192218```
@@ -197,39 +223,46 @@ The framework is configurable via `GeneratorConfig`:
197223
198224``` typescript
199225interface GeneratorConfig {
200- maxTables: number // Maximum tables per schema
201- maxColumns: number // Maximum columns per table
202- minRows? : number // Minimum rows per table
203- maxRows? : number // Maximum rows per table
204- maxRowsPerTable: number // Maximum rows per table
205- minCommands? : number // Minimum commands per test
206- maxCommands: number // Maximum commands per test
207- maxQueries: number // Maximum queries per test
208- floatTolerance: number // Float comparison tolerance
226+ maxTables: number // Maximum tables per schema
227+ maxColumns: number // Maximum columns per table
228+ minRows? : number // Minimum rows per table
229+ maxRows? : number // Maximum rows per table
230+ maxRowsPerTable: number // Maximum rows per table
231+ minCommands? : number // Minimum commands per test
232+ maxCommands: number // Maximum commands per test
233+ maxQueries: number // Maximum queries per test
234+ floatTolerance: number // Float comparison tolerance
209235}
210236```
211237
212238## Validation Properties
213239
214240### ** Snapshot Equality**
241+
215242Ensures that TanStack DB query results exactly match SQLite oracle results.
216243
217244### ** Incremental Convergence**
245+
218246Verifies that query results remain consistent as the database state changes through mutations.
219247
220248### ** Optimistic Transaction Visibility**
249+
221250Validates that transaction state is properly managed and visible to queries.
222251
223252### ** Row Count Sanity**
253+
224254Confirms that row counts are consistent between TanStack DB and SQLite across all tables.
225255
226256### ** Query Feature Coverage**
257+
227258Tests that all query features (WHERE, JOIN, ORDER BY, etc.) work correctly.
228259
229260### ** Data Type Handling**
261+
230262Ensures all data types (strings, numbers, booleans, objects, arrays) are handled properly.
231263
232264### ** Error Handling**
265+
233266Validates that edge cases and error conditions are handled gracefully.
234267
235268## Benefits
@@ -245,4 +278,4 @@ Validates that edge cases and error conditions are handled gracefully.
245278- ** Performance Testing** : Add performance property validation
246279- ** Concurrency Testing** : Test concurrent query execution
247280- ** Migration Testing** : Validate schema migration scenarios
248- - ** Integration Testing** : Test with real application scenarios
281+ - ** Integration Testing** : Test with real application scenarios
0 commit comments