Testing
Ship SQL and Rust regression coverage for Turso/libsql work using the repo’s preferred `.sqltest` flow and documented `make` / `cargo` runners.
Overview
Turso testing is an agent skill for the Ship phase that documents how to write and run `.sqltest`, legacy TCL, Rust integration, and fuzz tests in the Turso/libsql repository.
Install
npx skills add https://github.com/tursodatabase/turso --skill testingWhat is this skill?
- Maps four test types—`.sqltest`, legacy TCL `.test`, Rust integration, and fuzz—and states `.sqltest` is preferred for n
- Documents runners: `make test`, `make test-single`, `make -C testing/sqltests run-cli`, and `cargo run -p test-runner`.
- Explains converting legacy TCL tests with the `convert` command as migration path to `testing/sqltests`.
- Shows `.sqltest` syntax with `@database`, `test` blocks, and pipe-delimited `expect` rows for multi-backend runs.
- Notes `.sqltest` cases can execute against CLI, Rust bindings, and other backends from one file.
- Four documented test types: `.sqltest`, TCL `.test`, Rust integration, and fuzz.
- Preferred location for new tests: `testing/sqltests/tests/*.sqltest`.
Adoption & trust: 703 installs on skills.sh; 19.1k GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
You are changing SQL behavior in the Turso codebase but do not know which test format to add, where files go, or which `make`/`cargo` command reproduces CI.
Who is it for?
Solo or indie contributors hacking on Turso/libsql who need SQL compat tests that can run across multiple backends.
Skip if: Builders who only consume hosted Turso from an app repo and never clone or patch the core database project.
When should I use this skill?
Writing or migrating tests in the Turso/libsql repo, choosing between `.sqltest` and legacy TCL, or running documented test targets.
What do I get? / Deliverables
After following the guide you add `.sqltest` (or the right legacy/integration) cases in the correct tree and run the matching runner before opening a PR.
- New or migrated `.sqltest` files under `testing/sqltests/tests/`
- Targeted TCL, integration, or fuzz cases with passing local runs
Recommended Skills
Journey fit
Testing guidance is shelved under Ship because it governs how you verify correctness before release, not how you ideate or market the product. The skill is entirely about test types, locations, runners, and authoring—canonical fit for the testing subphase.
How it compares
Use this procedural test map instead of guessing SQLite-style TCL-only habits when the project standard is `.sqltest` plus `test-runner`.
Common Questions / FAQ
Who is testing for?
Database contributors, agent-assisted maintainers, and small teams working in the Turso/libsql monorepo who must keep SQL compatibility honest across backends.
When should I use testing?
Use it in Ship/testing when adding SQL features, migrating TCL `.test` files, authoring `.sqltest` expectations, or choosing between integration and fuzz coverage before merge.
Is testing safe to install?
It is documentation for local `make` and `cargo test` workflows; review the Security Audits panel on this Prism page before trusting any third-party skill package in your environment.
SKILL.md
READMESKILL.md - Testing
# Testing Guide ## Test Types & When to Use | Type | Location | Use Case | |------|----------|----------| | `.sqltest` | `testing/sqltests/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/sqltests. 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/sqltests run-cli # OR cargo run -p test-runner -- run <test-file or directory> # Rust unit/integration tests (full workspace) cargo test ``` ## Writing Tests ### .sqltest (Preferred) ``` @database :default: test example-addition { SELECT 1 + 1; } expect { 2 } test example-multiple-rows { SELECT id, name FROM users WHERE id < 3; } expect { 1|alice 2|bob } ``` Location: `testing/sqltests/tests/*.sqltest` You 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 testing/sqltests 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 ### 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/system/testing.db` has `users` and `products` tables. See [docs/testing.md](../../../docs/testing.md) for schema. ## Logging During Tests ```bash RUST_LOG=none,turso_core=trace make test ``` Output: `testing/system/test.log`. Warning: very verbose.