Skip to content

xpd test

Check rule examples and review diagnostic and fix snapshots Use xpd test when you write your own rules. It checks the valid and invalid examples of each project rule, and the snapshots of their issues and fixes. A snapshot is a saved file of the issues and fixes that a rule gives on its invalid examples, such as rule-tests/__snapshots__/team-no-print-snapshot.yml.

A test file has the ast-grep fields id, valid and invalid. A valid example must give no issue from its rule, and an invalid example must give one. A case can set path, so that the rule's files and ignores globs and the language detection see that file name. The default engine runs each example through the same scanner as xpd check, with import gates, value proofs and version bounds. --engine structural runs ast-grep's own test runner, which checks plain rules without them.

Terminal window
xpd test [OPTIONS]

--engine <ENGINE>

Run domain checks with xpd, or raw structural checks with ast-grep.

Default: xpd.

Values: xpd, structural.

-c, --config <CONFIG>

The project file to read instead of the nearest sgconfig.yml.

-t, --test-dir <TEST_DIR>

Read the test cases in this folder instead of the testConfigs of sgconfig.yml.

--snapshot-dir <SNAPSHOT_DIR>

The snapshot folder inside the test folder.

Default: __snapshots__.

-f, --filter <FILTER>

Test only the rules whose id matches this regular expression.

--skip-snapshot-tests

Check only the valid and invalid examples, and no snapshot.

Cannot be combined with --update-all, --interactive.

-U, --update-all

Accept every changed snapshot and write it.

-i, --interactive

Ask about each changed snapshot before writing it.

Cannot be combined with --format.

--format <FORMAT>

Print text, or JSON with each case's id, source and status and the failed count.

Default: text.

Values: text, json.

xpd new makes the project, the rule and an empty test file.

Terminal window
$ xpd new project --pack team --yes --format json | jq -c .item
"project"
$ xpd new rule team/no-print --pattern 'print($X)' --message 'Use the project logger.' --with-test --yes --format json | jq -c .id
"team/no-print"

With this test file, the first run fails because no snapshot exists yet. xpd test -U then writes the snapshot.

rule-tests/team/no-print-test.yml
id: team/no-print
valid:
- "log(1)"
invalid:
- "import team\nprint(1)"
Terminal window
$ xpd test
team/no-print: passed
team/no-print: snapshot mismatch
2 cases, 1 failed
$ xpd test -U
team/no-print: passed
team/no-print: updated
2 cases, 0 failed

--format json prints each case with its id, source and status, and the failed count.

Exit code Meaning
0 Every example and snapshot passed, or was updated
1 An example or a snapshot failed
2 The command could not run, for example because no case matched