Skip to content

README.md

Latest commit

 

History

History
26 lines (18 loc) · 3.36 KB

README.md

File metadata and controls

26 lines (18 loc) · 3.36 KB
Raw

Tests

ClickHouse Reference Tests

The clickhouse-reference-*.test.ts suites run the parser and formatters against (most of) the SELECT statements in ClickHouse's test suite.

For each input file in tests/clickhouse-reference, these tests

  1. (clickhouse-reference-ast.test.ts) Run parse() on the input and compare the output AST to the expected AST — ClickHouse's own EXPLAIN AST json = 1 output, generated by the clickhouse binary. The comparison uses formatExplainJson (see src/json-explain.ts), which removes node metadata (location/parent/comments) and the library-only fields absent from the reference AST, leaving exactly the ClickHouse-native view. <AST Error> and <Query Parameters> entries in the expected file are skipped.
  2. (clickhouse-reference-explain.test.ts) Run formatExplain() on the input and compare it to the canonical explain output. This ensures that the parser is parsing all of the information that ClickHouse does.
  3. (clickhouse-reference-format.test.ts) Run format() on the AST and compare the output to the expected format.
  4. (clickhouse-reference-round-trip.test.ts) Run parse() on the formatted SQL and compare the output AST to the AST from parsing the original input. The comparison uses stripVolatile (only location/parent and the non-semantic explain-only flags removed), so comments and the semantic library-only fields must survive the round trip too.

Related Scripts

  • scripts/filter-reference-queries.ts is used to clean up unsupported files and statements from the original test input set.
  • scripts/generate-expected-outputs.ts is used to generate the expected outputs for each input file. Run this when changing formatting or AST output.
    • Use npm run generate:expected-outputs to run this script
    • Updates to expected outputs should be persisted in git, so that reviewers can be aware of changes to parser and formatter outputs.
    • By default, this script will not generate any EXPLAIN outputs for inputs that already have EXPLAIN outputs (since these are reference outputs generated by ClickHouse). Pass --regenerate-all-references (e.g. npm run generate:expected-outputs -- --regenerate-all-references) to overwrite every existing AST and explain file as well, or --regenerate-changed-references to overwrite only those whose input .sql file has uncommitted git changes (staged, working-tree, or untracked).
    • When EXPLAIN or AST outputs need to be generated, the script will automatically start a ClickHouse container via docker compose up -d, wait for it to be ready, and stop it (docker compose down) on exit. If a ClickHouse server is already running at the expected URL, it is reused and left running.
  • npm run diff:ast / diff:format / diff:explain show this library's output, the expected output, and a diff between them for one or more reference cases (a .sql filename, comma-separated list, or glob) — the fastest way to debug a failing reference case. npm run parse / format / explain print just the output (for a reference case or for raw SQL via --sql). Pass -h for usage.

Query Params Tests

The query-params.test.ts tests parsing and formatting of query parameters. ClickHouse EXPLAIN AST requires substitutions to be set for each query parameter, so the reference tests don't cover these cases.