Skip to content
Skills Library
Data & analytics · Testing

setup

/setup

Set BigTesty up in a project to test BigQuery SQL on real BigQuery - install it with uv, authenticate on GCP, write the bigtesty.yaml config (datasets, tables, DDL, labels, CMEK, cleanup, max_bytes_billed) and run the tests in CI (GitHub Actions, GitLab CI, Cloud Build). Use when adding BigTesty to a project, writing or reviewing a bigtesty.yaml, wiring the tests in a pipeline, or upgrading from BigTesty 0.x.

Repository
bigtesty ↗
Licence
MIT
Last repository change
24.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
4
Deprecation

No signals detected. Repository changed on 24.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Set BigTesty up in a project to test BigQuery SQL on real BigQuery - install it with uv, authenticate on GCP, write the bigtesty.yaml config (datasets, tables, DDL, labels, CMEK, cleanup, max_bytes_billed) and run the tests in CI (GitHub Actions, GitLab CI, Cloud Build). Use when adding BigTesty to a project, writing or reviewing a bigtesty.yaml, wiring the tests in a pipeline, or upgrading from BigTesty 0.x.

Original author description

Set BigTesty up in a project to test BigQuery SQL on real BigQuery - install it with uv, authenticate on GCP, write the bigtesty.yaml config (datasets, tables, DDL, labels, CMEK, cleanup, max_bytes_billed) and run the tests in CI (GitHub Actions, GitLab CI, Cloud Build). Use when adding BigTesty to a project, writing or reviewing a bigtesty.yaml, wiring the tests in a pipeline, or upgrading from BigTesty 0.x.

How it works

  1. Install
  2. Authenticate
  3. Project layout
  4. bigtesty.yaml
  5. Run
  6. CI
  7. Upgrading from 0.x
Original SKILL.md headings · 118 lines, 608 words
SKILL.md preview
---
name: setup
description: Set BigTesty up in a project to test BigQuery SQL on real BigQuery - install it with uv, authenticate on GCP, write the bigtesty.yaml config (datasets, tables, DDL, labels, CMEK, cleanup, max_bytes_billed) and run the tests in CI (GitHub Actions, GitLab CI, Cloud Build). Use when adding BigTesty to a project, writing or reviewing a bigtesty.yaml, wiring the tests in a pipeline, or upgrading from BigTesty 0.x.
---

# Setting BigTesty up

BigTesty runs the tests on **real BigQuery**, in ephemeral datasets created for each run and deleted at the end.
No emulator, no mock: the SQL under test is the production SQL.

## Install

```bash
uv add --dev bigtesty        # a dev dependency, locked in uv.lock (preferred)
uv tool install bigtesty     # or a standalone CLI, e.g. for the tests of another language
```

Python 3.11+. The package is also a pytest plugin, and the Docker image `groupbees/bigtesty` runs the CLI without
Python.

## Authenticate

Application Default Credentials, nothing specific to BigTesty:

```bash
gcloud auth application-default login
```

The user or service account needs `roles/bigquery.user` on the **test project** (create datasets, run jobs). Use a
dedicated test project, never the production one: the SQL references are rewritten to the ephemeral datasets, so the
production project can stay hardcoded in the SQL (see `project_aliases`).

## Project layout

```text
bigtesty.yaml                         # the datasets and tables, found from the current directory and its parents
schema/monitoring/job_failure.json    # BigQuery JSON schemas (bq show --schema --format=prettyjson)
ddl/monitoring/*.sql                  # views, functions, procedures created in each ephemeral dataset
tests/monitoring/*.bigtesty.yaml      # the test files, see the writing-tests skill
```

All the paths are relative to the file that declares them.

## bigtesty.yaml

Declare **every dataset referenced by the SQL under test**, with the tables the tests load or read. Copy the schemas
of the production tables rather than retyping them.

```yaml
# yaml-language-server: $schema=https://raw.githubusercontent.com/tosun-si/bigtesty/main/schemas/bigtesty-config.schema.json

location: EU                      # project comes from --project / GOOGLE_CLOUD_PROJECT, or `project:`
tests: tests

datasets:
  - id: monitoring                # the dataset ID as written in the SQL
    tables:
      - id: job_failure
        schema_file: schema/monitoring/job_failure.json
        partitioning: { type: DAY, field: dwhCreationDate }
        clustering: [featureName, jobName]
      - id: job_failure_summary
        schema:
          - { name: featureName, type: STRING, mode: REQUIRED }
          - { name: failuresCount, type: INT64, mode: REQUIRED }
    ddl_files: [ddl/monitoring/*.sql]

project_aliases: [my-prod-project]   # projects hardcoded in the SQL, rewritten too
cleanup: always                      # on_success keeps the datasets of a failed run, to debug it in BigQuery
max_bytes_billed: 1000000000         # a guard per query job
labels: { team: data }               # on the datasets and the query jobs, for the billing export
```

Optional fields, only when needed:

- `kms_key_name`: CMEK, in the config or per dataset. The key must be in the location of the datasets (`europe`
  for `EU`, `us` for `US`) and the BigQuery encryption service account
  (`bq show --encryption_service_account`) needs `roles/cloudkms.cryptoKeyEncrypterDecrypter` on it.
- `sql_renderer` + `vars`: the template engine of the team, for templated production SQL (writing-tests skill).
- `table_expiration_hours` (6): safety net if a run is killed. `max_workers` (8): parallel scenarios and jobs.
- The keys `bigtesty` and `bigtesty_run_id` of `labels` are reserved.

Check the files without calling BigQuery: `bigtesty validate`.

## Run

```bash
bigtesty test                          # or: pytest (one test per scenario)
bigtesty test -k merge --cleanup never -v
bigtesty gc --older-than-hours 6       # datasets left by killed or kept runs
```

Exit code: 0 passed, 1 a scenario failed, 2 invalid config or test file, or authentication error.

## CI

The same commands, with Workload Identity Federation (no service account key) and the project in
`GOOGLE_CLOUD_PROJECT`. GitHub Actions:

```yaml
permissions: { contents: read, id-token: write }
steps:
  - uses: actions/checkout@v4
  - uses: google-github-actions/auth@v2
    with:
      workload_identity_provider: ${{ vars.WORKLOAD_IDENTITY_PROVIDER }}
      service_account: ${{ vars.SA_CI_EMAIL }}
  - uses: astral-sh/setup-uv@v6
    with: { enable-cache: true }
  - run: uv sync --frozen
  - run: uv run pytest --junitxml=report.xml
```

GitLab CI and Cloud Build: same steps, see https://tosun-si.github.io/bigtesty/running-tests/ci/github-actions/ and
the pages next to it. Runnable projects: https://github.com/tosun-si/bigtesty/tree/main/examples.

## Upgrading from 0.x

1.0 dropped Pulumi and the GCS state: `tables.json` becomes `bigtesty.yaml`, the `definition_*.json` files become
`*.bigtesty.yaml` test files with paths relative to themselves. Follow
https://tosun-si.github.io/bigtesty/start-here/migration/.

Versions

RepositoryScoreLicence
This page · tosun-si/bigtesty100MIT
HwangSlater/harness-fit100MIT
nesquikm/dev-process-toolkit100MIT
userKael/rastro100MIT
als-apg/osprey100BSD-3-Clause
dedujeong/gemba100Apache-2.0
eigenwise/eigenwise-toolshed100MIT
awrshift/agent-memory-kit100MIT
lifecycle-innovations-limited/claude-ops100MIT

Database snapshot: 13.11.2026 · package version 113d75812957 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100writing-tests
    Write BigTesty test files (*.bigtesty.yaml) that test BigQuery SQL - a query, a script, a MERGE, a procedure - with given rows, a when step and then assertions (expected rows, row_count, Python functions). Use when testing BigQuery SQL with BigTesty, adding a scenario, choosing…
  • 100troubleshooting
    Find why a BigTesty run fails and fix it - a failed assertion diff, an invalid config or test file (exit code 2), a GCP authentication or permission error, a location or CMEK error, a query over max_bytes_billed, a SQL reference that was not rewritten, or datasets left in…
  • 100bigquery-basics
    Manages datasets, tables, and jobs in BigQuery. Use when you need to interact with BigQuery, run SQL queries, manage BigQuery resources (datasets, tables, views), or perform basic data ingestion and analysis.
  • 100bigquery-basics
    Manages datasets, tables, and jobs in BigQuery. Use when you need to interact with BigQuery, run SQL queries, manage BigQuery resources (datasets, tables, views), or perform basic data ingestion and analysis.
  • 100bigquery-basics
    Manages datasets, tables, and jobs in BigQuery. Use when you need to interact with BigQuery, run SQL queries, manage BigQuery resources (datasets, tables, views), or perform basic data ingestion and analysis.
  • 100bigquery-optimization
    提供优化 BigQuery 环境(容量规划、版本)、存储资产(分区、聚簇、存储生命周期、 计费模式)和 SQL 查询的工作流。适用于优化成本、建模版本迁移、调整预留规模、 评估逻辑存储与物理存储、设计表分区/聚簇、生成表 DDL、迁移未分区表、 管理分区过期、优化单个 SQL 查询,或评估加速结构(搜索索引、物化视图、BI Engine)。 不适用于原始用量报告(请使用 bigquery-observability)、查询执行计划分析、 错误排查,或诊断特定作业为何缓慢(请使用 bigquery-troubleshooting)。

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.