@database <db-spec>
@database <db-spec>

setup <name> {
    <sql>
}

@setup <name>
@setup <name>
@skip "reason"
test <name> {
    <sql>
}
expect [modifier] {
    <expected-output>
}

# Snapshot tests (for EXPLAIN output)
@setup <name>
snapshot <name> {
    <sql>
}

@database :memory:
@database :temp:
@database :default:
@database :default-no-rowidalias:
@database path/to/file.db readonly

# Writable file - both memory and temp allowed
@database :memory:
@database :temp:

# Readonly file - only readonly paths allowed
@database testing/testing.db readonly
@database testing/testing_small.db readonly

# Default databases - pre-generated with fake data
@database :default:

# Default database without rowid alias
@database :default-no-rowidalias:

setup <name> {
    <sql-statements>
}

setup users {
    CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT, age INTEGER);
    INSERT INTO users VALUES (1, 'Alice', 30), (2, 'Bob', 25);
}

setup products {
    CREATE TABLE products (id INTEGER PRIMARY KEY, name TEXT, price REAL);
    INSERT INTO products VALUES (1, 'Widget', 9.99);
}

@skip-file "reason"
@skip-file-if <condition> "reason"
@requires-file <capability> "reason"

@database :memory:
@skip-file-if mvcc "MVCC not supported for this file"
@requires-file trigger "all tests need trigger support"

test example {
    SELECT 1;
}
expect {
    1
}

test <name> {
    <sql>
}
expect {
    <expected-output>
}

column1|column2|column3
value1|value2|value3

value1
value2

# Test with no setup
test select-constant {
    SELECT 42;
}
expect {
    42
}

# Test with single setup
@setup users
test select-users {
    SELECT id, name FROM users ORDER BY id;
}
expect {
    1|Alice
    2|Bob
}

# Test composing multiple setups
@setup users
@setup products
test select-join {
    SELECT u.name, p.name, p.price
    FROM users u, products p
    WHERE u.id = 1 LIMIT 1;
}
expect {
    Alice|Widget|9.99
}

# Test expecting error
test select-missing-table {
    SELECT * FROM nonexistent;
}
expect error {
    no such table
}

# Test with regex pattern
test select-random {
    SELECT random();
}
expect pattern {
    ^-?\d+$
}

# Test with unordered comparison
@setup users
test select-unordered {
    SELECT name FROM users;
}
expect unordered {
    Bob
    Alice
}

# Skipped test (unconditional)
@skip "known bug #123"
test select-buggy-feature {
    SELECT buggy();
}
expect {
    result
}

# Conditionally skipped test (only skipped in MVCC mode)
@skip-if mvcc "total_changes not supported in MVCC mode"
test total-changes {
    CREATE TABLE t (id INTEGER PRIMARY KEY);
    INSERT INTO t VALUES (1), (2), (3);
    SELECT total_changes();
}
expect {
    3
}

# Backend-specific test (only runs with CLI backend)
@backend cli
test cli-specific-feature {
    SELECT sqlite_version();
}
expect pattern {
    ^3\.\d+\.\d+$
}

# Backend-specific test (only runs with Rust backend)
@backend rust
test rust-specific-feature {
    SELECT 'rust-only';
}
expect {
    rust-only
}

# Test requiring a specific capability
@requires trigger "this test uses triggers"
test trigger-test {
    CREATE TABLE t (id INTEGER PRIMARY KEY);
    CREATE TRIGGER tr AFTER INSERT ON t BEGIN SELECT 1; END;
    INSERT INTO t VALUES (1);
    SELECT 'triggered';
}
expect {
    triggered
}

snapshot <name> {
    <sql>
}

tests/
  my-tests.sqltest
  snapshots/
    my-tests__query-plan-name.snap

@database :memory:

setup schema {
    CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT);
    CREATE INDEX idx_users_name ON users(name);
}

setup data {
    INSERT INTO users VALUES (1, 'Alice'), (2, 'Bob');
}

# Snapshot captures EXPLAIN QUERY PLAN + EXPLAIN output
@setup schema
@setup data
snapshot query-plan-by-id {
    SELECT * FROM users WHERE id = 1;
}

@setup schema
@setup data
snapshot query-plan-by-name {
    SELECT * FROM users WHERE name = 'Alice';
}

file            = { file_directive | database_decl | setup_block | test_case | snapshot_case }

file_directive  = "@skip-file" STRING NEWLINE
                | "@skip-file-if" skip_condition STRING NEWLINE
                | "@requires-file" capability STRING NEWLINE

database_decl   = "@database" database_spec NEWLINE
database_spec   = ":memory:" | ":temp:" | ":default:" | ":default-no-rowidalias:" | PATH ["readonly"]

setup_block     = "setup" IDENTIFIER block
test_case       = { decorator } "test" IDENTIFIER block expect_block
snapshot_case   = { decorator } "snapshot" IDENTIFIER block

decorator       = "@setup" IDENTIFIER NEWLINE
                | "@skip" STRING NEWLINE
                | "@skip-if" skip_condition STRING NEWLINE
                | "@backend" IDENTIFIER NEWLINE
                | "@requires" capability STRING NEWLINE

skip_condition  = "mvcc"
                | "sqlite"

capability      = "trigger" | "strict" | "materialized_views"

expect_block    = "expect" [expect_modifier] block

expect_modifier = "error" | "pattern" | "unordered"

block           = "{" { any_content } "}"

IDENTIFIER      = [a-zA-Z_][a-zA-Z0-9_-]*
STRING          = '"' { any_char } '"'
PATH            = [^\s]+
NEWLINE         = '\n'

For each @database:
    For each test (in parallel):
        1. Create fresh database connection
        2. Execute composed setups in order
        3. Execute test SQL
        4. Compare result with expectation
        5. Close connection

@setup users      # Executed first
@setup products   # Executed second
@setup orders     # Executed third
test my-test {
    ...
}

# This is a comment
@database :memory:

# Another comment
test example {
    SELECT 1;
}
expect {
    1
}

// Core types in src/parser/ast.rs
pub struct TestFile {
    pub databases: Vec<DatabaseConfig>,
    pub setups: HashMap<String, String>,
    pub tests: Vec<TestCase>,
    pub snapshots: Vec<SnapshotCase>,
    pub global_skip: Option<Skip>,        // @skip-file / @skip-file-if
    pub global_requires: Vec<Requirement>, // @requires-file
}

pub struct TestCase {
    pub name: String,
    pub sql: String,
    pub expectations: Expectations,
    pub modifiers: CaseModifiers,
}

pub struct SnapshotCase {
    pub name: String,
    pub sql: String,
    pub modifiers: CaseModifiers,
}

pub struct CaseModifiers {
    pub setups: Vec<SetupRef>,
    pub skip: Option<Skip>,
    pub backend: Option<Backend>,
    pub requires: Vec<Requirement>,
}

pub struct Skip {
    pub reason: String,
    pub condition: Option<SkipCondition>,
}

pub enum SkipCondition {
    Mvcc,  // Skip when MVCC mode is enabled
    Sqlite, // Skip when running against sqlite CLI backend
}

pub enum Capability {
    Trigger,           // CREATE TRIGGER support
    Strict,            // STRICT tables support
    MaterializedViews, // Materialized views (experimental)
}

pub struct Requirement {
    pub capability: Capability,
    pub reason: String,
}

pub enum Backend {
    Rust,
    Cli,
    Js,
}

pub enum Expectation {
    Exact(Vec<String>),
    Pattern(String),
    Unordered(Vec<String>),
    Error(Option<String>),
}