Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

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: NotFound is a DataNotFoundError, Unavailable a retryable DatabaseError, 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_percentage and snapshot_time are 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_job and 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) or BIGNUMERIC(p,s) column and checked against its precision;
  • the length checks of STRING(n) and BYTES(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.