Testing with the fake
The library provides a fake BigQuery for your tests, in the bigquery::testing module.
BigQueryFake runs a gRPC server on a loopback port and hands out a real BigQueryDb connected
to it, so the code under test runs unchanged, through the same requests, codecs, retries and
errors as against BigQuery. It needs no credentials and no network.
A test scripts the fake with your own serde types:
- a query rule answers the statement it matches with rows, DML counts or a failure;
- a table holds rows, which reads serve and writes append to, and which the test reads back;
- a fault makes the calls of one RPC fail.
The tests need an async runtime in your dev-dependencies:
[dev-dependencies]
tokio = { version = "1", features = ["macros", "rt"] }
The examples below share a row type and the code under test, and each of them is the body of a
#[tokio::test] async fn ...() -> BigQueryResult<()>:
use bigquery::*;
use serde::{Deserialize, Serialize};
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
struct Order {
id: i64,
customer: String,
total: f64,
}
const SHOP: BigQueryDatasetId = BigQueryDatasetId::from_static("shop");
const ORDERS: BigQueryTableId = BigQueryTableId::from_static("orders");
const ORDERS_OF: &str = "SELECT id, customer, total FROM shop.orders WHERE customer = @customer";
async fn orders_of(db: &BigQueryDb, customer: &str) -> BigQueryResult<Vec<Order>> {
db.fluent().query(ORDERS_OF).param("customer", customer).obj().query().await
}
async fn save(db: &BigQueryDb, orders: &[Order]) -> BigQueryResult<BigQueryWriteSummary> {
db.fluent().insert().into(SHOP.table(ORDERS)).objects(orders).execute().await
}
Queries
There is no SQL engine in the fake. A query answers only as a rule scripts it:
use bigquery::*;
use serde::{Deserialize, Serialize};
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
struct Order { id: i64, customer: String, total: f64 }
const ORDERS_OF: &str = "SELECT id, customer, total FROM shop.orders WHERE customer = @customer";
async fn orders_of(db: &BigQueryDb, customer: &str) -> BigQueryResult<Vec<Order>> {
db.fluent().query(ORDERS_OF).param("customer", customer).obj().query().await
}
#[tokio::main(flavor = "current_thread")]
async fn main() -> BigQueryResult<()> {
use bigquery::testing::BigQueryFake;
let fake = BigQueryFake::start().await?;
let alice = vec![Order { id: 1, customer: "Alice".into(), total: 120.0 }];
let rule = fake
.when_query_match(ORDERS_OF)
.param("customer", "Alice")
.returns_rows(|columns| columns.from_type::<Order>(), &alice)?;
assert_eq!(orders_of(fake.db(), "Alice").await?, alice);
assert_eq!(rule.calls(), 1);
Ok(())
}
The rows are any Serialize type, and their columns are declared as a table schema declares them,
here with |columns| columns.from_type::<Order>(). A rule matches:
- the SQL text exactly, with no whitespace or case folding;
- a statement from
sql_file!by the text of its file; - any parameters, unless the rule declares some with
.param(..),.params(..)or.positional_param(..). Then the call’s named parameters must equal them as a set, and its positional ones in order.
Rules are tried in the order they were registered, and the first that matches answers.
.times(n) limits a rule to n calls, retries included, so a later rule answers the calls after
them. Besides returns_rows, a rule answers with returns_dml for a DML statement and the rows it
changed, returns_statement for DDL, fails for a refused call and fails_job for a job that
fails once it runs. One rule answers every terminal of a call: the rows for query(), the stats
for execute() and the schema for dry_run(), with .bytes_processed(..) if set.
fake.when_query(|query| ...) matches with your own code instead of the SQL text. The closure
gets the call’s SQL and its parameters, read back as any Deserialize type:
use bigquery::*;
use serde::{Deserialize, Serialize};
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
struct Order { id: i64, customer: String, total: f64 }
const ORDERS_OF: &str = "SELECT id, customer, total FROM shop.orders WHERE customer = @customer";
async fn orders_of(db: &BigQueryDb, customer: &str) -> BigQueryResult<Vec<Order>> {
db.fluent().query(ORDERS_OF).param("customer", customer).obj().query().await
}
#[tokio::main(flavor = "current_thread")]
async fn main() -> BigQueryResult<()> {
use bigquery::testing::BigQueryFake;
let fake = BigQueryFake::start().await?;
let alice = vec![Order { id: 1, customer: "Alice".into(), total: 120.0 }];
let rule = fake
.when_query(|query| {
query.sql().contains("FROM shop.orders")
&& query.param::<String>("customer").is_some_and(|name| name.starts_with('A'))
})
.returns_rows(|columns| columns.from_type::<Order>(), &alice)?;
assert_eq!(orders_of(fake.db(), "Alice").await?, alice);
assert_eq!(rule.calls(), 1);
Ok(())
}
query.param::<T>(name) reads a named parameter, with the name compared ignoring case as
BigQuery compares it, and query.positional_param::<T>(index) a positional one, the first at 0.
Both return None when the call has no such parameter or its value does not read as T. A STRUCT
reads as a struct or a map, an ARRAY as a Vec, and a RANGE as BigQueryRange. .param(..) and
.positional_param(..) narrow a when_query rule as they narrow a SQL one.
Tables, reads and writes
A table on the fake holds rows. fake.table(..) creates it with its columns, and its dataset if
that is missing, and .rows(..) adds rows a read is served:
use bigquery::*;
use serde::{Deserialize, Serialize};
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
struct Order { id: i64, customer: String, total: f64 }
const SHOP: BigQueryDatasetId = BigQueryDatasetId::from_static("shop");
const ORDERS: BigQueryTableId = BigQueryTableId::from_static("orders");
#[tokio::main(flavor = "current_thread")]
async fn main() -> BigQueryResult<()> {
use bigquery::testing::BigQueryFake;
let fake = BigQueryFake::start().await?;
let orders = vec![
Order { id: 1, customer: "Alice".into(), total: 120.0 },
Order { id: 2, customer: "Bob".into(), total: 80.5 },
];
fake.table(SHOP.table(ORDERS), |columns| columns.from_type::<Order>())
.rows(&orders)
.create()?;
let read: Vec<Order> = fake.db().fluent().select().from(SHOP.table(ORDERS)).obj().query().await?;
assert_eq!(read, orders);
Ok(())
}
Writes append to the table, and fake.rows::<T>(table) reads back the rows written:
use bigquery::*;
use serde::{Deserialize, Serialize};
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
struct Order { id: i64, customer: String, total: f64 }
const SHOP: BigQueryDatasetId = BigQueryDatasetId::from_static("shop");
const ORDERS: BigQueryTableId = BigQueryTableId::from_static("orders");
async fn save(db: &BigQueryDb, orders: &[Order]) -> BigQueryResult<BigQueryWriteSummary> {
db.fluent().insert().into(SHOP.table(ORDERS)).objects(orders).execute().await
}
#[tokio::main(flavor = "current_thread")]
async fn main() -> BigQueryResult<()> {
use bigquery::testing::BigQueryFake;
let fake = BigQueryFake::start().await?;
fake.table(SHOP.table(ORDERS), |columns| columns.from_type::<Order>())
.create()?;
let orders = vec![
Order { id: 1, customer: "Alice".into(), total: 120.0 },
Order { id: 2, customer: "Bob".into(), total: 80.5 },
];
let summary = save(fake.db(), &orders).await?;
assert_eq!(summary.rows_written, 2);
let written: Vec<Order> = fake.rows(SHOP.table(ORDERS))?;
assert_eq!(written, orders);
Ok(())
}
rows returns the visible rows, in the order they were acknowledged. Rows become visible as
BigQuery makes them visible for each write mode:
- the default and committed streams: when acknowledged;
- a buffered stream: up to the last flushed offset;
- a pending stream: at its commit, and never without one.
Rows are matched to the table’s columns by name, ignoring case, and the fields of a RECORD column the same way. Rows written before a column or a RECORD field was added, and flushed or committed after, read it as NULL, as do the rows the table already holds.
A table read is served the table’s rows, projected to the selected columns. The fake evaluates
no filter, so a read with a row restriction needs a rule,
fake.when_read(table).row_restriction(..), with the rows it returns.
fake.when_rows_rejected::<T>(table, reason, |row| ...) fails each append request that has a row
the predicate accepts, with a row error per such row, and writes nothing of that request, as
BigQuery does. A row written from a serde type fails the same way when it has
a value beyond the precision of its NUMERIC(p,s) or BIGNUMERIC(p,s) column, and a value with
more decimal places than the scale is rounded.
A CDC writer’s rows are recorded as changes and not applied to the table’s rows.
fake.changes::<T>(table) returns them, each with its change type and sequence number.
Datasets and tables, from fake.create_dataset(..), fake.table(..) or the code under test, are
the fake’s state, and the admin calls are served from it.
Faults and retries
A query rule’s fails scripts the failure of a query. fake.when_fault(rpc).fails(..) does the
same for every other RPC, and .on_table(..) narrows it to the calls on one table. A fault answers
before every rule and before the tables, as one of:
BigQueryFakeFault::status(code, message), a gRPC status, which the client maps as it maps BigQuery’s own:NotFoundis aDataNotFoundError,Unavailablea retryableDatabaseError, etc.;BigQueryFakeFault::ConnectionDropped, a connection closed without an answer, which the client retries as a transport error;BigQueryFakeFault::Hang, a call that never answers. The client waits until its own timeout, if it has one.
Retries against the fake wait no backoff, so a test that scripts failures runs at full speed. A failure a retry gets past, then an outage the client gives up on:
use bigquery::*;
use serde::{Deserialize, Serialize};
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
struct Order { id: i64, customer: String, total: f64 }
const ORDERS_OF: &str = "SELECT id, customer, total FROM shop.orders WHERE customer = @customer";
async fn orders_of(db: &BigQueryDb, customer: &str) -> BigQueryResult<Vec<Order>> {
db.fluent().query(ORDERS_OF).param("customer", customer).obj().query().await
}
#[tokio::main(flavor = "current_thread")]
async fn main() -> BigQueryResult<()> {
use bigquery::testing::{BigQueryFake, BigQueryFakeCode, BigQueryFakeFault};
let fake = BigQueryFake::start().await?;
let alice = vec![Order { id: 1, customer: "Alice".into(), total: 120.0 }];
let unavailable =
|| BigQueryFakeFault::status(BigQueryFakeCode::Unavailable, "backend went away");
let lost = fake.when_query_match(ORDERS_OF).times(1).fails(unavailable())?;
let answer = fake
.when_query_match(ORDERS_OF)
.param("customer", "Alice")
.returns_rows(|columns| columns.from_type::<Order>(), &alice)?;
let outage = fake
.when_query_match(ORDERS_OF)
.param("customer", "Bob")
.fails(unavailable())?;
assert_eq!(orders_of(fake.db(), "Alice").await?, alice);
assert_eq!((lost.calls(), answer.calls()), (1, 1));
let failed = orders_of(fake.db(), "Bob").await;
assert!(matches!(&failed, Err(err) if err.retry_possible()), "{failed:?}");
assert_eq!(outage.calls(), 4, "the first attempt and max_retries = 3 retries");
Ok(())
}
On AppendRows, ConnectionDropped writes the request and then drops the connection, as an
acknowledgement lost in transit. The client sends the request again, so on the default stream,
which is at least once, its rows are written twice. A write with .exactly_once() sends it with
its offset, and the table keeps one copy:
use bigquery::*;
use serde::{Deserialize, Serialize};
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
struct Order { id: i64, customer: String, total: f64 }
const SHOP: BigQueryDatasetId = BigQueryDatasetId::from_static("shop");
const ORDERS: BigQueryTableId = BigQueryTableId::from_static("orders");
#[tokio::main(flavor = "current_thread")]
async fn main() -> BigQueryResult<()> {
use bigquery::testing::{BigQueryFake, BigQueryFakeFault, BigQueryFakeRpc};
let fake = BigQueryFake::start().await?;
fake.table(SHOP.table(ORDERS), |columns| columns.from_type::<Order>())
.create()?;
let lost = fake
.when_fault(BigQueryFakeRpc::AppendRows)
.times(1)
.fails(BigQueryFakeFault::ConnectionDropped)?;
let orders = vec![Order { id: 1, customer: "Alice".into(), total: 120.0 }];
fake.db()
.fluent()
.insert()
.into(SHOP.table(ORDERS))
.objects(&orders)
.exactly_once()
.execute()
.await?;
assert_eq!(fake.rows::<Order>(SHOP.table(ORDERS))?, orders);
assert_eq!(lost.calls(), 1);
Ok(())
}
Unmatched calls
A call that nothing answers, such as a query no rule matches or an RPC the fake does not serve,
fails with Unimplemented, which the client does not retry. The fake records it, and
fake.verify() panics with every such call and the rules that were there to answer it. It also
panics for a rule limited with .times(n) that did not answer exactly n calls.
verify runs when the fake is dropped, so a test fails on an unscripted call even when the code
under test swallows its error:
use bigquery::*;
use serde::{Deserialize, Serialize};
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
struct Order { id: i64, customer: String, total: f64 }
const ORDERS_OF: &str = "SELECT id, customer, total FROM shop.orders WHERE customer = @customer";
async fn orders_of(db: &BigQueryDb, customer: &str) -> BigQueryResult<Vec<Order>> {
db.fluent().query(ORDERS_OF).param("customer", customer).obj().query().await
}
#[tokio::main(flavor = "current_thread")]
async fn main() -> BigQueryResult<()> {
use bigquery::testing::BigQueryFake;
let fake = BigQueryFake::start().await?;
fake.when_query_match(ORDERS_OF)
.param("customer", "Alice")
.returns_rows(|columns| columns.from_type::<Order>(), Vec::<Order>::new())?;
let unmatched = orders_of(fake.db(), "Bob").await;
assert!(matches!(&unmatched, Err(err) if !err.retry_possible()), "{unmatched:?}");
drop(fake); // Panics: no rule answers the query for Bob
Ok(())
}
If the test is already panicking when the fake is dropped, the problems are logged with
tracing::error! instead, so the first panic is the one the test reports.
Choosing the fake or BigQuery at startup
fake.db() is a real BigQueryDb connected to the fake’s loopback server, so the fake needs no
trait shared with the real client. Code that takes a BigQueryDb, as an argument or a field of
the application state, runs unchanged against either. This also makes it possible to run the
whole application against the fake, with a factory that picks one at startup from the
application’s own configuration, such as an environment variable. The library itself reads no
variable for this.
The factory returns an owner of the client. Dropping a BigQueryFake stops its server and runs
verify(), so the owner keeps the fake alive next to the client it hands out:
use bigquery::*;
use serde::{Deserialize, Serialize};
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
struct Order { id: i64, customer: String, total: f64 }
const SHOP: BigQueryDatasetId = BigQueryDatasetId::from_static("shop");
const ORDERS: BigQueryTableId = BigQueryTableId::from_static("orders");
const ORDERS_OF: &str = "SELECT id, customer, total FROM shop.orders WHERE customer = @customer";
async fn orders_of(db: &BigQueryDb, customer: &str) -> BigQueryResult<Vec<Order>> {
db.fluent().query(ORDERS_OF).param("customer", customer).obj().query().await
}
pub struct AppBigQuery {
db: BigQueryDb,
_fake: Option<bigquery::testing::BigQueryFake>,
}
impl AppBigQuery {
pub fn db(&self) -> &BigQueryDb {
&self.db
}
}
/// BigQuery in `project`, or a seeded fake when `APP_BIGQUERY=fake` is set.
pub async fn bigquery_db(project: &str) -> BigQueryResult<AppBigQuery> {
if std::env::var("APP_BIGQUERY").as_deref() == Ok("fake") {
let fake = bigquery::testing::BigQueryFake::start().await?;
seed(&fake)?;
return Ok(AppBigQuery {
db: fake.db().clone(),
_fake: Some(fake),
});
}
Ok(AppBigQuery {
db: BigQueryDb::new(project).await?,
_fake: None,
})
}
fn seed(fake: &bigquery::testing::BigQueryFake) -> BigQueryResult<()> {
let alice = vec![Order { id: 1, customer: "Alice".into(), total: 120.0 }];
fake.table(SHOP.table(ORDERS), |columns| columns.from_type::<Order>())
.rows(&alice)
.create()?;
fake.when_query_match(ORDERS_OF)
.returns_rows(|columns| columns.from_type::<Order>(), &alice)?;
Ok(())
}
#[tokio::main(flavor = "current_thread")]
async fn main() -> BigQueryResult<()> {
// The rest of the application sees only the client
let bigquery = bigquery_db("my-gcp-project-id").await?;
let orders = orders_of(bigquery.db(), "Alice").await?;
let _ = orders;
Ok(())
}
The fake answers a query only from a rule, so the fake branch seeds a rule for every query the
application sends, besides the tables it reads and writes. An application run against the fake
with APP_BIGQUERY=fake cargo run panics when the fake is dropped if a call went unanswered, as
a test does. An application that wants the fake out of its production builds can put the fake
branch behind a feature of its own.
Limits
The fake binds its own port, so tests run in parallel, and a fake is Send + Sync, so a test can
share it with the tasks it spawns. A call sees the rules registered before it arrives.
Tokio’s paused time, #[tokio::test(start_paused = true)], is not supported. A paused runtime
jumps to its next timer whenever it is idle, and waiting on the fake’s loopback socket counts as
idle.
The fake does not provide:
- SQL evaluation. The DDL that
.sync()sends for a rename, drop or widen reaches the query rules and does not change the table; - read filters. A row restriction needs a read rule, and
sample_percentageandsnapshot_timeare served the current rows; - failures in the middle of a read stream, and partial acknowledgements of an append;
- polling of running jobs, other than for
fails_joband queries with a destination table; - CDC changes applied to the table’s rows;
- Arrow appends in Arrow types other than the table’s own. A decimal is the exception: it is
rescaled to the scale of its
NUMERIC(p,s)orBIGNUMERIC(p,s)column and checked against its precision; - the length checks of
STRING(n)andBYTES(n), default values, request limits and quotas; - a read that selects a field of a STRUCT column, such as
.fields(["address.city"]); ListJobs,DeleteJob, models, routines, row access policies, table snapshots and copies.
Full example available here.