testing

Source excerpt starting at line 1.

1---2name: testing3description: How to write tests, when to use each type of test, and how to run them. Contains information about conversion of `.test` to `.sqltest`, and how to write `.sqltest` and rust tests4---5# Testing Guide6 7## Test Types & When to Use8 9| Type | Location | Use Case |10|------|----------|----------|11| `.sqltest` | `sqlite/conformance/sqlite-sqltests/` | SQL compatibility. **Preferred for new tests** |12| TCL `.test` | `testing/` | Legacy SQL compat (being phased out) |13| Rust integration | `tests/integration/` | Regression tests, complex scenarios |14| Fuzz | `tests/fuzz/` | Complex features, edge case discovery |15 16**Note:** TCL tests are being phased out in favor of the `.sqltest` suites in `sqlite/conformance/`. The `.sqltest` format allows the same test cases to run against multiple backends (CLI, Rust bindings, etc.).17 18## Running Tests19 20```bash21# Main test suite (TCL compat, sqlite3 compat, Python wrappers)22make test23 24# Single TCL test25make test-single TEST=select.test26 27# SQL test runner28make -C sqlite/conformance run-cli29 30# OR31cargo run -p sqltest -- run <test-file or directory>32 33# Rust unit/integration tests (full workspace)34cargo test35```36 37## Writing Tests38 39### .sqltest (Preferred)40```41@database :default:42 43test example-addition {44    SELECT 1 + 1;45}46expect {47    248}49 50test example-multiple-rows {51    SELECT id, name FROM users WHERE id < 3;52}53expect {54    1|alice55    2|bob56}57```58Location: `sqlite/conformance/sqlite-sqltests/*.sqltest`59 60You must start converting TCL tests with the `convert` command from the test runner (e.g `cargo run -- convert <TCL_test_path> -o <out_dir>`). It is not always accurate, but it will convert most of the tests. If some conversion emits a warning you will have to write by hand whatever is missing from it (e.g unroll a for each loop by hand). Then you need to verify the tests work by running them with `make -C sqlite/conformance run-rust`, and adjust their output if something was wrong with the conversion. Also, we use harcoded databases in TCL, but with `.sqltest` we generate the database with a different seed, so you will probably need to change the expected test result to match the new database query output. Avoid changing the SQL statements from the test, just change the expected result 61 62### TCL63```tcl64do_execsql_test_on_specific_db {:memory:} test-name {65  SELECT 1 + 1;66} {2}67```68Location: `testing/*.test`69 70### Rust Integration71```rust72// tests/integration/test_foo.rs73#[test]74fn test_something() {75    let conn = Connection::open_in_memory().unwrap();76    // ...77}78```79 80## Key Rules81 82- Every functional change needs a test83- Test must fail without change, pass with it84- Prefer in-memory DBs: `:memory:` (sqltest) or `{:memory:}` (TCL)85- Don't invent new test formats. Follow existing patterns86- Write tests first when possible87 88## Test Database Schema89 90`testing/system/testing.db` has `users` and `products` tables. See [docs/testing.md](../../../docs/testing.md) for schema.91 92## Logging During Tests93 94```bash95RUST_LOG=none,turso_core=trace make test96```97Output: `testing/system/test.log`. Warning: very verbose.98