Testing Guide

Test Types & When to Use

Type	Location	Use Case
`.sqltest`	`testing/runner/tests/`	SQL compatibility. Preferred for new tests
TCL `.test`	`testing/`	Legacy SQL compat (being phased out)
Rust integration	`tests/integration/`	Regression tests, complex scenarios
Fuzz	`tests/fuzz/`	Complex features, edge case discovery

Note: TCL tests are being phased out in favor of testing/runner. The .sqltest format allows the same test cases to run against multiple backends (CLI, Rust bindings, etc.).

Running Tests

bash

# Main test suite (TCL compat, sqlite3 compat, Python wrappers)
make test

# Single TCL test
make test-single TEST=select.test

# SQL test runner
make -C testing/runner run-cli

# Rust unit/integration tests (full workspace)
cargo test

Writing Tests

.sqltest (Preferred)

sql

@database :memory:

@query
SELECT 1 + 1;
@expected
2

Location: testing/runner/tests/*.sqltest

TCL

tcl

do_execsql_test_on_specific_db {:memory:} test-name {
  SELECT 1 + 1;
} {2}

Location: testing/*.test

Rust Integration

rust

// tests/integration/test_foo.rs
#[test]
fn test_something() {
    let conn = Connection::open_in_memory().unwrap();
    // ...
}

Key Rules

Every functional change needs a test
Test must fail without change, pass with it
Prefer in-memory DBs: :memory: (sqltest) or {:memory:} (TCL)
Don't invent new test formats. Follow existing patterns
Write tests first when possible

Test Database Schema

testing/testing.db has users and products tables. See docs/testing.md for schema.

Logging During Tests

bash

RUST_LOG=none,turso_core=trace make test

Output: testing/test.log. Warning: very verbose.