Skip to content

Commit 87691aa

Browse files
committed
Fix Prettier formatting issues
- Run prettier --write to fix all formatting issues - All files now pass prettier --check - Resolves CI formatting errors
1 parent 6c7062b commit 87691aa

File tree

1 file changed

+44
-11
lines changed

1 file changed

+44
-11
lines changed

packages/db/tests/property-testing/README.md

Lines changed: 44 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -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+
3439
Tests 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+
4551
Rapid 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+
5461
Systematic 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+
6573
Unit 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
8292
const 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
94105
const state = {
@@ -106,6 +117,7 @@ for (const command of commands) {
106117
```
107118

108119
### 3. **Property Validation**
120+
109121
```typescript
110122
// Check snapshot equality
111123
const 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
126139
const 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+
144159
Uses `better-sqlite3` for deterministic comparison against TanStack DB's results.
145160

146161
### **Comprehensive SQL Translation**
162+
147163
Converts 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+
155173
Handles 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+
162182
Gracefully 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
176199
pnpm test:property:quick
177200
```
178201

179202
### Full Property Tests
203+
180204
```bash
181205
pnpm test:property
182206
```
183207

184208
### Coverage Report
209+
185210
```bash
186211
pnpm test:property:coverage
187212
```
188213

189214
### Example Usage
215+
190216
```bash
191217
pnpm test:property:example
192218
```
@@ -197,39 +223,46 @@ The framework is configurable via `GeneratorConfig`:
197223

198224
```typescript
199225
interface 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+
215242
Ensures that TanStack DB query results exactly match SQLite oracle results.
216243

217244
### **Incremental Convergence**
245+
218246
Verifies that query results remain consistent as the database state changes through mutations.
219247

220248
### **Optimistic Transaction Visibility**
249+
221250
Validates that transaction state is properly managed and visible to queries.
222251

223252
### **Row Count Sanity**
253+
224254
Confirms that row counts are consistent between TanStack DB and SQLite across all tables.
225255

226256
### **Query Feature Coverage**
257+
227258
Tests that all query features (WHERE, JOIN, ORDER BY, etc.) work correctly.
228259

229260
### **Data Type Handling**
261+
230262
Ensures all data types (strings, numbers, booleans, objects, arrays) are handled properly.
231263

232264
### **Error Handling**
265+
233266
Validates 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

Comments
 (0)