
testing
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 tests
- Installs
- 1.3K
- Last 24h
- —
- Trending rank
- —
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/tursodatabase/turso --skill testing- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads testing automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
Testing Guide
Test Types & When to Use
| Type | Location | Use Case |
|---|---|---|
.sqltest | sqlite/conformance/sqlite-sqltests/ | 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 the .sqltest suites in sqlite/conformance/. The .sqltest format allows the same test cases to run against multiple backends (CLI, Rust bindings, etc.).
Running Tests
# 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 sqlite/conformance run-cli
# OR
cargo run -p sqltest -- 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: sqlite/conformance/sqlite-sqltests/*.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 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
TCL
do_execsql_test_on_specific_db {:memory:} test-name {
SELECT 1 + 1;
} {2}
Location: testing/*.test
Rust Integration
// tests/integration/test_foo.rs
#[test]
fn test_something() {
let conn = Connection::open_in_memory().unwrap();
// ...
}
Assertions
Prefer the asserting crate for anything more than trivial assertions. The assertions it offers are extensive
and make tests more readable. Some simple examples:
use asserting::prelude::*;
assert_that!(conn.execute("SELECT * FROM t1;")).is_err();
assert_that_code!(|| parse(bad_input)).panics_with_message("unexpected token");
assert_that!(&rows)
.has_length(3)
.any_satisfies(|r| r
.name == "bob")
.first_element_ref()
.is_equal_to(&Row { id: 1, name: "alice".into() });
assert_that!(&header)
.named("page 2 header")
.satisfies_with_message("be a leaf table page", |h| h[0] == 0x0d);
// soft assertions: mark the test as failed but don't stop
verify_that!(&plan)
.starts_with("SEARCH")
.contains("USING INDEX")
.soft_panic();
crate::assertions adds row! for result rows, plus column and query-plan
assertions:
use crate::assertions::{AssertColumn, AssertQueryPlan, Cell, NULL};
assert_that!(limbo_exec_rows(&conn, "SELECT id, name FROM t ORDER BY id"))
.is_equal_to(vec![row![1, "alice"], row![2, NULL]]);
assert_that!(limbo_exec_rows(&conn, "SELECT id FROM t WHERE id = 1"))
.single_element()
.is_equal_to(row![1]);
assert_that!(limbo_exec_rows(&conn, "SELECT id, name FROM t"))
.column(1)
.contains(Cell::from("alice"));
assert_that!(limbo_exec_rows(&conn, "EXPLAIN QUERY PLAN SELECT id FROM t WHERE name = 'a'"))
.uses_index("idx_name")
.searches_table("t")
.has_table_access_order(["t"]);
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 for schema.
Logging During Tests
RUST_LOG=none,turso_core=trace make test
Output: testing/system/test.log. Warning: very verbose.
FAQ
What does the testing skill do?
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 tests
How do I install testing?
Run npx skills add https://github.com/tursodatabase/turso --skill testing in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/testing/ (personal) or .claude/skills/testing/ (project).
Which AI agents can use testing?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is testing safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains testing?
It is published by tursodatabase in tursodatabase/turso. It has 1,264 recorded installs.
More from tursodatabase/turso
code-quality
tursodatabase/turso
General Correctness rules, Rust patterns, comments, avoiding over-engineering. When writing code always take these into account
index-knowledge
tursodatabase/turso
Generate hierarchical AGENTS.md knowledge base for a codebase. Creates root + complexity-scored subdirectory documentation.
debugging
tursodatabase/turso
How to debug tursodb using Bytecode comparison, logging, ThreadSanitizer, deterministic simulation, and corruption analysis tools
async-io-model
tursodatabase/turso
Explanations of common asynchronous patterns used in tursodb. Involves IOResult, state machines, re-entrancy pitfalls, CompletionGroup. Always use these patterns in core when doing anything IO
storage-format
tursodatabase/turso
SQLite file format, B-trees, pages, cells, overflow, freelist that is used in tursodb
pr-workflow
tursodatabase/turso
General guidelines for Commits, formatting, CI, dependencies, security
Popular testing & qa skills
tdd
mattpocock/skills
Test-driven development. Use when the user wants to build features or fix bugs test-first, mentions "red-green-refactor", or wants integration tests.
grilling
mattpocock/skills
Grill the user relentlessly about a plan, decision, or idea. Use when the user wants to stress-test their thinking, or uses any 'grill' trigger phrases.
migrate-to-shoehorn
mattpocock/skills
Migrate test files from as type assertions to @total-typescript/shoehorn. Use when user mentions shoehorn, wants to replace as in tests, or needs partial test data.
run-train
lllllllama/rigorpilot-skills
Rigor Train skill for deep learning research repositories. Use when a documented or selected training command should be run conservatively for startup verification, short-run verification, full kickoff, or resume, with command, config, seed, log, checkpoint, status, and metric evidence written to standardized trainoutputs/. Do not use for environment setup, exploratory sweeps, speculative idea implementation, or end-to-end orchestration.
test-driven-development
obra/superpowers
Use when implementing any feature or bugfix, before writing implementation code
finishing-a-development-branch
obra/superpowers
Use when implementation is complete, all tests pass, and you need to decide how to integrate the work