Skip to content

std::sql::testing

Testing code that uses std::sql. Fake is a Conn that runs no SQL: it records every statement and transaction command sent to it, keeps track of which statements took effect (a rolled-back transaction’s did not), and responds to each statement with a function the test gives it. conformance is the suite every driver runs against its own connections: it checks each rule Conn states, transactions and savepoints above all, and names each rule a driver breaks.

Import with import std::sql::testing.

struct Fake

opaque — construction surface is private to its defining module

A recording Conn for tests. It runs no SQL: each statement is handled by answer, which gets the statement and the statements in effect as the connection sees them (committed ones, then those of each open transaction and savepoint), and an exec returns the number of rows answer gives. A statement answer gives Ok takes effect; one it gives Err does not.

begin, commit and rollback follow Conn’s rules, so the fake passes the conformance suite, and record what a driver would send: BEGIN, COMMIT and ROLLBACK for a transaction, and SAVEPOINT sp1, RELEASE SAVEPOINT sp1 and ROLLBACK TO SAVEPOINT sp1 for a savepoint, numbered by its depth. close follows them too, and records CLOSE the first time; it discards the effects of every transaction still open. Every Conn that begin returns shares the connection’s record.

fake = Fake.new()

result = sql.transaction(fake, fn tx ->
    _ = Conn.exec(tx, Sql"INSERT INTO users (name) VALUES (${"Ada"})")?
    Ok(Unit)
end)

assert result == Ok(Unit)
assert Fake.log(fake) == ["BEGIN", "INSERT INTO users (name) VALUES (?1)", "COMMIT"]
assert Fake.committed(fake) == [Sql"INSERT INTO users (name) VALUES (${"Ada"})"]
fn new(dialect: Dialect = Dialect.Other("fake"), answer: (Statement, List<Statement>) -> Result<List<Row>, sql.Error> = answer_nothing) -> Fake

type function on Fake

A fake connection with nothing recorded. By default it calls itself Dialect.Other("fake") and responds to every statement with no rows.

rows: List<Row> = [Row.new("SELECT 1 AS n", [("n", Value.Int(1))])]
fake = Fake.new(answer: fn _, _ -> Ok(rows))
assert Conn.query(fake, Sql"SELECT 1 AS n") == Ok(rows)
assert Conn.exec(fake, Sql"DELETE FROM t") == Ok(1)
fn log(fake: Fake) -> List<String>

type function on Fake

Everything sent, in order: each statement as Statement’s Display writes it, and each transaction command.

fn statements(fake: Fake) -> List<Statement>

type function on Fake

The statements sent, in order, whether or not they took effect.

fn committed(fake: Fake) -> List<Statement>

type function on Fake

The statements in effect outside every transaction: those run outside one, and those of transactions that committed. A statement of a transaction still open, or of one rolled back, is not here.

fake = Fake.new()

_ = sql.transaction<Unit>(fake, fn tx ->
    _ = Conn.exec(tx, Sql"INSERT INTO t VALUES (1)")?
    Err(sql.Error.Timeout)
end)

assert Fake.committed(fake) == []
assert Fake.log(fake) == ["BEGIN", "INSERT INTO t VALUES (1)", "ROLLBACK"]
fn is_closed(fake: Fake) -> Bool

type function on Fake

Whether close was called on the fake or on a Conn its begin returned.

fake = Fake.new()

answer = begin
    defer sql.close_quietly(fake)
    Conn.exec(fake, Sql"DELETE FROM t")
end

assert answer == Ok(0)
assert Fake.is_closed(fake)
assert Conn.ping(fake) == Err(sql.Error.Closed)
assert Fake.log(fake) == ["DELETE FROM t", "CLOSE"]

impl Conn for Fake

fn query(conn: Fake, statement: Statement) -> Result<List<Row>, sql.Error>

impl Conn.query

impl Conn for Fake

fn each_row(conn: Fake, statement: Statement, f: (Row) -> Bool) -> Result<Unit, sql.Error>

impl Conn.each_row

impl Conn for Fake

fn exec(conn: Fake, statement: Statement) -> Result<Int, sql.Error>

impl Conn.exec

impl Conn for Fake

fn begin_transaction(conn: Fake) -> Result<Conn, sql.Error>

impl Conn.begin_transaction

impl Conn for Fake

fn commit(tx: Fake) -> Result<Unit, sql.Error>

impl Conn.commit

impl Conn for Fake

fn rollback(tx: Fake) -> Result<Unit, sql.Error>

impl Conn.rollback

impl Conn for Fake

fn ping(conn: Fake) -> Result<Unit, sql.Error>

impl Conn.ping

impl Conn for Fake

fn dialect(conn: Fake) -> Dialect

impl Conn.dialect

impl Conn for Fake

fn close(conn: Fake) -> Result<Unit, sql.Error>

impl Conn.close

impl Debug for Fake

fn inspect(value: Fake) -> String

impl Debug.inspect

struct Failure
    rule: String
    message: String
end

A conformance rule a driver broke: the rule’s name and what happened. Its Display is rule: message.

failure = Failure{rule: "ping", message: "timed out"}
assert "${failure}" == "ping: timed out"

impl Display for Failure

fn to_string(failure: Failure) -> String

impl Display.to_string

impl Debug for Failure

fn inspect(value: Failure) -> String

impl Debug.inspect

impl Equatable for Failure

fn equal(a: Failure, b: Failure) -> Bool

impl Equatable.equal

fn conformance<C>(open: () -> Result<C, sql.Error>) -> List<Failure> where C: Conn

Run every conformance rule against connections from open, and return the rules broken, in the order rules lists them: none for a driver that conforms. Each rule opens a fresh connection, closes it when the rule ends (a close that fails breaks the rule), and creates a temporary table on it,

CREATE TEMPORARY TABLE nomi_conformance (n INTEGER NOT NULL, t TEXT)

which it writes with INSERT INTO nomi_conformance (n, t) VALUES (?1, ?2) and reads with SELECT n, t FROM nomi_conformance ORDER BY n. The timestamp and constraint rules create temporary tables of their own (nomi_conformance_times, nomi_conformance_parents and nomi_conformance_children).

The rules cover ping, parameters as values (a text holding quotes and --), NULL, reading a row by name and by position, each_row stopping, a transaction seeing its own writes, commit and rollback, savepoints (rolled back, committed inside a rolled-back transaction, and three deep), rollback after commit and after rollback as no-ops, commit and a statement after commit as Finished, and sql.transaction committing on Ok and rolling back on Err, on a trap and in a failed inner transaction, a second close as a no-op, every operation after close as Closed, closing a transaction closing its connection, closing a connection ending its transaction and savepoint, a deferred sql.close_quietly closing on Ok, on Err and on a trap, an Instant written an hour before and after CURRENT_TIMESTAMP comparing and sorting around it, and the names of a unique, primary-key, named check, not-null and foreign-key violation, each on temporary tables of its own. The rollback of an open transaction by a close is not checked: the suite’s table is temporary and goes with the connection.

A driver’s test calls it with a function that opens a connection to a scratch database:

test "the driver conforms"
    assert testing.conformance(fn -> sqlite.open(":memory:")) == []
end
assert conformance(fn -> Ok(Fake.new(answer: conformance_answer))) == []
fn rules() -> List<String>

The names of the conformance rules, in the order conformance runs them.

assert Iter.contains(rules(), "rollback after commit is a no-op")
fn conformance_answer(statement: Statement, visible: List<Statement>) -> Result<List<Row>, sql.Error>

An answer for Fake.new that runs the conformance suite’s own statements, so the suite can run against a fake: its queries read back the rows of the suite’s inserts in effect (an insert with no time is at the moment it is read), an insert that breaks one of the suite’s constraints returns that constraint’s error, and every other statement returns no rows.