testing/runner/docs/README.md
This directory contains documentation for the test-runner crate.
# Build
cargo build --release
# Check test file syntax
./target/release/test-runner check tests/
# Run tests
./target/release/test-runner run tests/ --binary ./target/release/tursodb
| Document | Description |
|---|---|
| DSL Specification | Complete specification of the .sqltest file format |
| CLI Usage | Command-line interface reference |
| Document | Description |
|---|---|
| Architecture | System architecture and backend trait design |
| Parallelism | Parallel execution strategy and implementation |
| Document | Description |
|---|---|
| CLI Backend | CLI backend implementation details |
| Adding Backends | Guide for implementing new SDK backends |
Example test files are available in the examples/ directory:
examples/basic.sqltest - Basic DSL syntax examplesexamples/joins.sqltest - Setup composition and join teststest-runner/
├── src/
│ ├── lib.rs # Public API exports
│ ├── main.rs # CLI binary entry point
│ ├── parser/ # DSL parser (Logos lexer)
│ │ ├── mod.rs # Parser entry point
│ │ ├── lexer.rs # Tokenizer
│ │ └── ast.rs # AST types
│ ├── backends/ # SQL execution backends
│ │ ├── mod.rs # SqlBackend trait
│ │ └── cli.rs # CLI subprocess backend
│ ├── runner/ # Test execution
│ │ ├── mod.rs # TestRunner, parallel execution
│ │ └── executor.rs # Single test executor
│ ├── comparison/ # Result comparison
│ │ ├── mod.rs # Comparison dispatcher
│ │ ├── exact.rs # Exact match (with diff)
│ │ ├── pattern.rs # Regex pattern match
│ │ └── unordered.rs # Set comparison
│ └── output/ # Output formatting
│ ├── mod.rs # OutputFormat trait
│ ├── pretty.rs # Colored terminal output
│ └── json.rs # JSON output for CI
├── docs/ # Documentation (this directory)
├── examples/ # Example test files
└── tests/ # Integration tests
# Database configuration
@database :memory:
# Named setup blocks
setup users {
CREATE TABLE users (id INT, name TEXT);
}
# Test with setup decorator
@setup users
test select-users {
SELECT * FROM users;
}
expect {
1|Alice
}
All tests are isolated by default:
The runner uses a trait-based backend system for extensibility:
trait SqlBackend {
fn create_database(&self, config: &DatabaseConfig)
-> Result<Box<dyn DatabaseInstance>>;
}
trait DatabaseInstance {
async fn execute(&mut self, sql: &str) -> Result<QueryResult>;
async fn close(self: Box<Self>) -> Result<()>;
}
| Crate | Purpose |
|---|---|
clap | CLI argument parsing |
logos | Lexer generation |
tokio | Async runtime & parallelism |
similar | Diff generation for comparisons |
colored | Terminal colors |
serde_json | JSON output |
MIT