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.
Exports
Section titled “Exports”struct Fake
Section titled “struct Fake”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"})"]
Fake.new
Section titled “Fake.new”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)
Fake.log
Section titled “Fake.log”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.
Fake.statements
Section titled “Fake.statements”fn statements(fake: Fake) -> List<Statement>
type function on Fake
The statements sent, in order, whether or not they took effect.
Fake.committed
Section titled “Fake.committed”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"]
Fake.is_closed
Section titled “Fake.is_closed”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"]
Fake.query
Section titled “Fake.query”impl Conn for Fake
fn query(conn: Fake, statement: Statement) -> Result<List<Row>, sql.Error>
impl Conn.query
Fake.each_row
Section titled “Fake.each_row”impl Conn for Fake
fn each_row(conn: Fake, statement: Statement, f: (Row) -> Bool) -> Result<Unit, sql.Error>
impl Conn.each_row
Fake.exec
Section titled “Fake.exec”impl Conn for Fake
fn exec(conn: Fake, statement: Statement) -> Result<Int, sql.Error>
impl Conn.exec
Fake.begin_transaction
Section titled “Fake.begin_transaction”impl Conn for Fake
fn begin_transaction(conn: Fake) -> Result<Conn, sql.Error>
Fake.commit
Section titled “Fake.commit”impl Conn for Fake
fn commit(tx: Fake) -> Result<Unit, sql.Error>
impl Conn.commit
Fake.rollback
Section titled “Fake.rollback”impl Conn for Fake
fn rollback(tx: Fake) -> Result<Unit, sql.Error>
impl Conn.rollback
Fake.ping
Section titled “Fake.ping”impl Conn for Fake
fn ping(conn: Fake) -> Result<Unit, sql.Error>
impl Conn.ping
Fake.dialect
Section titled “Fake.dialect”impl Conn for Fake
fn dialect(conn: Fake) -> Dialect
impl Conn.dialect
Fake.close
Section titled “Fake.close”impl Conn for Fake
fn close(conn: Fake) -> Result<Unit, sql.Error>
impl Conn.close
Fake.inspect
Section titled “Fake.inspect”impl Debug for Fake
fn inspect(value: Fake) -> String
impl Debug.inspect
struct Failure
Section titled “struct Failure”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"
Failure.to_string
Section titled “Failure.to_string”impl Display for Failure
fn to_string(failure: Failure) -> String
impl Display.to_string
Failure.inspect
Section titled “Failure.inspect”impl Debug for Failure
fn inspect(value: Failure) -> String
impl Debug.inspect
Failure.equal
Section titled “Failure.equal”impl Equatable for Failure
fn equal(a: Failure, b: Failure) -> Bool
impl Equatable.equal
testing.conformance
Section titled “testing.conformance”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))) == []
testing.rules
Section titled “testing.rules”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")
testing.conformance_answer
Section titled “testing.conformance_answer”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.