Skip to main content
DocumentationLibraryReference
On this page

Kater CLI Make and compare new

kater new test

Makes one test in a model's test file, and keeps the answer that the test expects.

Use it to pin a number that you checked, so that a later change cannot move it without notice. The test goes in your own users/<email>/tests/<model>.sql, unless you add --shared or --workspace.

Examples

Terminal window
# Add a test from the Kater SQL in totals.sql, run it one time and keep the rows it returns
kater new test july_2026_spend_by_platform --model semantic.ad_reporting --sql-file totals.sql --record
# Show the test as it would go in the file, and save nothing
kater new test july_2026_spend_by_platform --model semantic.ad_reporting --sql-file totals.sql --record --dry-run
# Add the test to the shared layer's test file, which everyone reads
kater new test july_2026_spend_by_platform --model semantic.ad_reporting --sql-file totals.sql --record --shared
# Add a test that expects the compiler to refuse the SQL in spend_total.sql
kater new test spend_without_currency --model semantic.ad_reporting --sql-file spend_total.sql --refused
# Check the model against a dbt mart, and pair the rows on platform and currency
kater new test matches_ad_report_mart --model semantic.ad_reporting --sql-file totals.sql --same-as-native mart.sql --key platform --key union__currency

Arguments

ArgumentDescription
<name>The test’s name, such as july_2026_spend_by_platform. No other test in the same file can have this name.

Options

OptionDescription
--connection <name>The connection, by its folder name under connections/. Leave it out when --workspace or --from-query names the connection, or when only one connection has the --model.
--model <model>The shared semantic model or Kater dataset that the test checks, by its name or typed address, such as semantic.ad_reporting. With --from-query, give the model that the query’s workspace reads, or leave it out.
--sql-file <file>A file of hand-written Kater SQL that reads the model. Give - to read the SQL from stdin.
--from-query <file>A saved workspace query to keep as the test, by its path. Its workspace’s root must read one shared model whole, with optional filters at most. With --workspace, give one of that workspace’s own queries. Do not give --sql-file with it.
--query-name <name>With --from-query, the query to keep, when the file holds more than one.
--picker-file <file>A JSON file that asks the question as field picker selections: fields, conditions, group, order and limit. Give it in place of --sql-file, or with it. With both, the two must return the same answer.
--recordRuns the test one time and keeps the rows that it returns as the expected answer.
--refusedCompiles the SQL and keeps the code that the compiler refuses it with, such as not_additive_across. Use it to pin a rule of the model. The test is not added when the SQL compiles.
--same-as-native <file>A file of read-only warehouse SQL, such as a query of a dbt mart. The test passes when the two answers are the same. Give --key with it.
--same-as-sql <file>A file of Kater SQL over any shared model. The test passes when the two answers are the same. Give --key with it.
--key <column>With --same-as-native or --same-as-sql, a column that pairs the rows of the two answers. You can give it more than one time.
--description <text>What you checked the answer against, such as the Ads Manager export for July 2026.
--question <text>The business question that the test answers, word for word as the model’s business_questions has it.
--draftMarks the test as not checked yet. A draft runs and reports, but it does not count toward readiness. A draft can leave out the expected answer: its first run that returns rows records them.
--workspace <path>A connection workspace, such as connections/snowflake_prod_connection/workspaces/ad_reporting. The test checks the workspace’s root and goes in the workspace’s tests/<root>.sql. Do not give --model or --shared with it.
--sharedAdds the test to the shared layer’s modeling/kater_objects/tests/<model>.sql, which everyone reads, in place of your own file. You need edit access to the shared models.
--as-of <date>The day that the test takes as today, such as 2026-09-27. Then a relative condition, such as the last 7 complete days, reads fixed dates.
--inputs-file <file>With --workspace, a JSON file with the root’s parameter values and filters: {"parameters": {...}, "filters": [...]}.
--given-file <file>Makes the test a fixture. The JSON file gives the rows of each table that the model reads, as [{"table": NAME, "rows": [{COLUMN: value}]}]. Every other table is empty. Give --record with it.
--dry-runShows the test as it would go in the file, with its recorded answer, and saves nothing.

It also takes the global options --json, --kater-root, --scope and --help.

One expected answer

Give one of --record, --refused, --same-as-native or --same-as-sql. Only a draft can leave them all out. A test must read one closed range of the model’s dates, so that its answer does not move as data loads. Kater refuses a test that has no closed range, except a refused test or a fixture. See Every test pins a fixed set of rows.

An example SQL file

The examples above read this file. It asks for spend and clicks by platform and currency in July 2026:

totals.sql
SELECT
  ad_reporting.platform,
  ad_reporting.union__currency,
  ad_reporting.sum__spend,
  ad_reporting.sum__clicks
FROM semantic.ad_reporting AS ad_reporting
WHERE
  KATER__IS_BETWEEN(ad_reporting.union__date_day, CAST('2026-07-01' AS DATE), CAST('2026-07-31' AS DATE))
GROUP BY
  ad_reporting.platform,
  ad_reporting.union__currency

See also