---
last_updated: "2026-11-04T12:15:44.000Z"
title: tb test
meta:
    description: Run and update tests for your Tinybird project
---

# tb test

Runs and updates tests for your Tinybird project.

The following subcommands are available:

{% table %}
  * Subcommand
  * Description
  ---
  * run [FILES]
  * Runs all the tests in the project or specific tests passed as arguments.
  ---
  * update PIPE
  * Updates the test's expectations.
{% /table %}

## Create test files

Create test YAML files manually in the `tests/` folder.

For the test file format, see [Test files](/forward/dev-reference/datafiles/test-files).

Example `tests/user_actions.yaml`:

```yaml
- name: user_actions_clicked
  description: Returns clicked actions only
  expected_http_status: 200
  parameters: action=CLICKED
  expected_result: |
    {"action":"CLICKED"}
```

Use `tb test update` to refresh expected results after changing a query.

## tb test run

Run all tests in the project with `tb test run`, or pass specific tests as arguments. Tests run with fixture data against your local.

For example, `tb test run tests/get_lego_sets_by_year.yaml` returns:

```bash
Running against Tinybird Local

» Building test environment
✓ Done!

» Running tests
* get_sets_by_theme_year.yaml
✓ get_sets_by_theme_year_2000s_range passed
✓ get_sets_by_theme_year_1990s_range passed
```

{% callout type="tip" %}
Tinybird creates a fresh workspace for each test run. Secrets don't persist between test runs. To avoid test failures, add a default value to your secrets: `{{ tb_secret("secret_name", "default_value") }}`.
{% /callout %}

### Control fixture loading

By default, `tb test run` auto-loads every fixture file whose name matches a Data Source (for example, `fixtures/user_actions.ndjson` for `datasources/user_actions.datasource`). Two options let you tailor this behavior:

{% table %}
  * Option
  * Default
  * Description
  ---
  * `--auto-fixtures / --no-auto-fixtures`
  * `--auto-fixtures`
  * Toggles the name-matching auto-load step. Use `--no-auto-fixtures` to skip it entirely.
  ---
  * `--fixture DATASOURCE=PATH`
  * unset
  * Loads `PATH` into `DATASOURCE`. Repeat the option to load several files. Entries apply in the order you pass them.
{% /table %}

You can combine the two options to get four different behaviors:

{% table %}
  * Command
  * Fixtures loaded
  ---
  * `tb test run`
  * Auto-loaded fixtures only.
  ---
  * `tb test run --fixture ...`
  * Auto-loaded fixtures first, then `--fixture` entries appended after, in the order you passed them.
  ---
  * `tb test run --no-auto-fixtures`
  * Nothing loaded. Useful for testing empty-state behavior.
  ---
  * `tb test run --no-auto-fixtures --fixture ...`
  * Only the `--fixture` entries. Each Data Source is truncated the first time it appears, so re-runs stay idempotent.
{% /table %}

`--fixture` accepts `.ndjson` and `.csv` files. Relative paths are resolved from the project root.

Example: load two files into `user_actions` and one extra into `sessions`, on top of the auto-loaded fixtures.

```shell
tb test run \
  --fixture user_actions=fixtures/user_actions_extra.ndjson \
  --fixture sessions=fixtures/sessions_edge_cases.ndjson \
  --fixture user_actions=fixtures/user_actions_backfill.ndjson
```

{% callout type="note" %}
When you combine `--auto-fixtures` (the default) with `--fixture` entries for the same Data Source, rows stack. To replace the auto-loaded rows entirely, add `--no-auto-fixtures`.
{% /callout %}

## tb test update

Updates the test's expectations. For example: `tb test update get_lego_sets_by_year`.

## Environment support

{% table %}
  * Environment
  * Supported
  * Description
  ---
  * `--local`
  * ✓ Yes (default)
  * Runs tests locally with fixture data.
  ---
  * `--cloud`
  * ✗ No
  * Tests run locally, not in cloud.
  ---
  * `--branch=BRANCH_NAME`
  * ✗ No
  * Tests run locally, not in branches.
{% /table %}