testing

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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.).

类型	位置	适用场景
`.sqltest`	`testing/runner/tests/`	SQL兼容性测试。优先用于新测试
TCL `.test`	`testing/`	遗留SQL兼容性测试（逐步淘汰中）
Rust集成测试	`tests/integration/`	回归测试、复杂场景测试
模糊测试	`tests/fuzz/`	复杂功能、边缘场景发现

注意： TCL测试正逐步被testing/runner替代。

.sqltest

格式允许相同的测试用例在多个后端（CLI、Rust绑定等）上运行。

Running Tests

运行测试

bash

undefined

bash

undefined

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

主测试套件（TCL兼容性、sqlite3兼容性、Python包装器）

make test

Single TCL test

单个TCL测试

make test-single TEST=select.test

SQL test runner

SQL测试运行器

make -C testing/runner run-cli

Rust unit/integration tests (full workspace)

Rust单元/集成测试（完整工作区）

cargo test

undefined

cargo test

undefined

Writing Tests

编写测试

.sqltest (Preferred)

.sqltest（推荐）

@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/runner/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/runner 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

@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
}

位置：

testing/runner/tests/*.sqltest

你必须使用测试运行器的

convert

命令来转换TCL测试（例如

cargo run -- convert <TCL测试路径> -o <输出目录>

）。转换并不总是完全准确，但它会转换大部分测试内容。如果转换过程中出现警告，你需要手动补充缺失的部分（例如手动展开for each循环）。然后你需要通过运行

make -C testing/runner run-rust

来验证测试是否正常工作，如果转换后的输出有问题，需要调整预期结果。另外，我们在TCL中使用硬编码的数据库，但在

.sqltest

中我们使用不同的种子生成数据库，因此你可能需要修改测试的预期结果以匹配新的数据库查询输出。避免修改测试中的SQL语句，只需调整预期结果即可。

TCL

TCL测试

tcl

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

Location:

testing/*.test

tcl

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

位置：

testing/*.test

Rust Integration

Rust集成测试

rust

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

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

每个功能变更都需要对应测试
测试在没有变更时必须失败，变更后必须通过
优先使用内存数据库：
```
:memory:
```
（sqltest）或
```
{:memory:}
```
（TCL）
不要创建新的测试格式，遵循现有模式
尽可能先编写测试

Test Database Schema

测试数据库 Schema

testing/system/testing.db

has

users

and

products

tables. See docs/testing.md for schema.

testing/system/testing.db

包含

users

和

products

表。Schema详情请查看docs/testing.md。

Logging During Tests

测试期间的日志记录

bash

RUST_LOG=none,turso_core=trace make test

Output:

testing/system/test.log

. Warning: very verbose.

bash

RUST_LOG=none,turso_core=trace make test

输出：

testing/system/test.log

。注意：内容非常详细。