A test is a fixed question with a fixed answer: these fields from this model, over this date range, return exactly these rows. Write a small suite when a model is done, check its numbers against something you trust, and run it whenever the model, its upstream data or Kater changes. Each model’s tests are in the Tests tab of the Shared models editor.

The Tests tab

Open a model in Shared models and select the Tests tab in the sidebar. It shows:

• Tests and how many the model has, with New test (+) and Run every test (the run button).
• Readiness. Not ready to hand off or Ready to hand off, then each readiness check with its detail, such as “0 of 16” for measures in a checked test.
• The model’s tests, each with its state, its name and its kind: Rows, Refused or Same as.

A model with no tests yet offers Generate drafts and New test. Under Business questions with no test, each of the model’s business questions has Make a test from it, which writes one draft test that answers that question.

A test, opened

Select a test in the list, and it opens in the main area. The bar at the top has Joins and rows to go back, the test’s state and name, its author, Show in Files, Record rows and Run. A test with no description says “No description yet. Add what you checked these numbers against.” Below it is the test’s block, as the file has it, which you edit in place. Under the block:

• Rows shows the expected rows, and after a run, what the run found.
• Paths shows each path the test checks: the picker request, the SQL the writer writes, and the other side of a same_as test.

Files keeps its own Tests view, with every test in the connection.

Where tests live

A model’s tests live in one file named after the model. tests/ad_reporting.sql holds the tests of semantic.ad_reporting.

Example

1
---
2
name: july_2026_totals_by_platform
3
model_type: test
4
description: Matches the Ads Manager exports for July 2026.
5
expect:
6
  columns: [platform, union__currency, sum__spend, sum__clicks]
7
  rows:
8
  - [facebook_ads, USD, 63963.91, 58844]
9
  - [google_ads, USD, 110747.05, 79509]
10
  - [tiktok_ads, USD, 12535.44, 19704]
11
---
12

13
SELECT
14
  ad_reporting.platform,
15
  ad_reporting.union__currency,
16
  ad_reporting.sum__spend,
17
  ad_reporting.sum__clicks
18
FROM semantic.ad_reporting AS ad_reporting
19
WHERE
20
  KATER__IS_BETWEEN(ad_reporting.union__date_day, CAST('2026-07-01' AS DATE), CAST('2026-07-31' AS DATE))
21
GROUP BY
22
  ad_reporting.platform,
23
  ad_reporting.union__currency

Each test is one block with its own frontmatter. A test compiles as a query in a workspace rooted in the model, so grouping, KATER__ conditions and currency rules apply exactly as they do for a stakeholder’s query. Nothing reads a test: it is not in pickers, the catalog or Explore.

Keys

Two paths, three expectations

• A picker tests what a stakeholder’s clicks produce. Kater writes its SQL at each run, so the test also checks the SQL writer.
• A SQL body tests hand-written Kater SQL. With both, each path is checked on its own.

A refused test keeps a rule from being lost. This one proves that Spend cannot be totalled across currencies:

1
---
2
name: spend_needs_currency
3
model_type: test
4
expect:
5
  refused: not_additive_across
6
---
7

8
SELECT
9
  ad_reporting.platform,
10
  EVAL(ad_reporting.sum__spend)
11
FROM semantic.ad_reporting AS ad_reporting
12
GROUP BY
13
  ad_reporting.platform

A same_as test checks the model against a source you trust, such as a dbt mart:

1
expect:
2
  same_as:
3
    key:
4
    - platform
5
    - union__account_id
6
    - union__date_day
7
    native: |
8
      SELECT
9
        platform,
10
        CAST(account_id AS VARCHAR) AS union__account_id,
11
        DATE_TRUNC('MONTH', date_day) AS union__date_day,
12
        SUM(spend) AS sum__spend
13
      FROM DEMO_DB.ANALYTICS_AD_REPORTING.AD_REPORTING__AD_REPORT
14
      WHERE date_day BETWEEN '2025-05-01' AND '2026-07-31'
15
      GROUP BY 1, 2, 3

Every test pins a fixed set of rows

Each side of a test filters the model’s date to the same closed range, so the answer does not move as data loads. A test without one is refused, except a refused test or a fixture test.

• A closed range. A picker condition is_between, a BETWEEN in SQL, or KATER__IS_BETWEEN.
• A relative window, pinned. is_within_last with complete: true, and as_of to fix today.
• Settled data. A range that ends within 30 days of today gets a warning, because ad platforms restate recent conversions.

A fixture test runs the model on rows you give, as a dbt unit test does. Every other table it reads is empty:

1
name: account_with_two_currencies_counts_spend_twice
2
model_type: test
3
given:
4
- table: facebook_ads__account_report
5
  rows:
6
  - {SOURCE_RELATION: fb, DATE_DAY: '2026-07-01', ACCOUNT_ID: 1, CURRENCY: USD}
7
  - {SOURCE_RELATION: fb, DATE_DAY: '2026-07-01', ACCOUNT_ID: 1, CURRENCY: EUR}
8
- table: facebook_ads__ad_report
9
  rows:
10
  - {SOURCE_RELATION: fb, DATE_DAY: '2026-07-01', ACCOUNT_ID: 1, AD_ID: 10, SPEND: 100, CLICKS: 7}
11
expect:
12
  columns: [platform, union__currency, sum__spend, sum__clicks]
13
  rows:
14
  - [facebook_ads, EUR, 100.0, 7]
15
  - [facebook_ads, USD, 100.0, 7]

Write tests

From a terminal, kater new test NAME --model semantic.ad_reporting --sql-file totals.sql --record runs the SQL once and keeps its rows. --refused keeps the code the compiler refuses it with, and --same-as-native mart.sql --key platform writes a reference test.

Run tests

• In the editor. Run every test in the Tests tab, or Model › Run tests, runs the model’s tests. Run on an open test runs that one. Record rows, or Model › Record test rows, keeps what the run found as the expected rows.
• From a terminal. Use the commands below.

Columns compare by position, and numbers at the precision their format shows, such as cents for currency(…, 2). A failure whose SQL is unchanged since its last pass means the data changed, and the test says so.

Ready to hand off

The top of the Tests tab says whether a model is ready for stakeholders, and lists each check with its detail. kater test readiness --model semantic.ad_reporting gives the same answer. Readiness only informs. Nothing is ever blocked for a model without tests.

Run them every night

A test job in kater.config.yaml with after: its sync job runs the shared and workspace tests after each sync, so restated data shows as failing tests in the header’s test bell. See Scheduled jobs.