Skip to main content
DocumentationLibraryReference
On this page

Kater CLI Build and check test

kater test generate

Writes a starting set of draft tests for a shared model.

Each test runs one time on the warehouse and goes in your own test file as a draft. Then you check each draft, and mark it with kater test update --checked.

Examples

Terminal window
# Write five draft tests for the shared ad_reporting model, in your own test file
kater test generate --model semantic.ad_reporting
# Print the plan, and run and write nothing
kater test generate --model semantic.ad_reporting --dry-run
# Write 12 tests to the shared layer's test file
kater test generate --model semantic.ad_reporting --count 12 --shared
# Also write a test for each business question that no test answers yet
kater test generate --model semantic.ad_reporting --from-questions
# Write the test of one business question only
kater test generate --model semantic.ad_reporting --question "Which accounts contribute the most spend, clicks, and impressions?"

Options

OptionDescription
--connection <name>The connection, by its folder name under connections/. Leave it out when only one connection has the --model.
--model <model>Required. The shared semantic model or Kater dataset, by its name or typed address, such as semantic.ad_reporting.
--count <n>How many tests to write, 5 by default, one of each shape. A lower count takes the shapes in order. A higher count adds tests that cover more of the model.
--window <range>The dates that every test reads, as FIELD=START..END or START..END, such as union__date_day=2026-07-01..2026-07-31. Without it, Kater uses the range that the file’s tests read. Or else it uses the latest complete month that ended at least 30 days ago.
--from-questionsAlso writes a field picker test for each of the model’s business questions that the file does not answer yet, as Explore writes one. Each test keeps the question that it answers.
--question <text>Writes the test of only this business question, word for word as the model’s business_questions has it. You cannot use it with --count or --from-questions.
--sharedWrites to the shared layer’s modeling/kater_objects/tests/<model>.sql, which everyone reads, in place of your own users/<email>/tests/<model>.sql. You need edit access to the shared models.
--dry-runPrints the plan, and runs and writes nothing.

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

What it writes

  • Five shapes first. By default, it writes one test of each shape: field picker to rows, field picker and Kater SQL to rows, Kater SQL to refused, field picker with operations to rows, and field picker to the same answer as native SQL. It does not write a shape again that the file has already.
  • More coverage with --count. Each test after the first five covers more of what no test covers yet: a measure, a grain, a kind of dimension, an operation family or a rule.
  • No native SQL. Kater never writes native SQL. The same_as test reports that it has no answer until you write its native side.
  • One date range. Every test reads the same closed range of the model’s date field. See --window.
  • Failures are not written. A test that fails is reported, and Kater leaves it out of the file.
  • The same tests each time. On a model that did not change, a second run writes nothing that it wrote before.
  • Business questions. A question that the model’s fields cannot answer is reported, not written. A question that the file answers already is skipped.

What it prints

The first line gives the date range and how many tests it plans, or what it wrote to which file. Then each test has one line: its number, its shape and what it asks. A test that the file has already is marked (in the file). After that come the tests that it did not write and why, and what to check before you accept a draft. The last line names what no test covers yet, and the --count that covers it.

See also