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.
xpd test [OPTIONS]Options
Section titled “Options”--engine
Section titled “--engine”--engine <ENGINE>
Run domain checks with xpd, or raw structural checks with ast-grep.
Default: xpd.
Values: xpd, structural.
--config
Section titled “--config”-c, --config <CONFIG>
The project file to read instead of the nearest sgconfig.yml.
--test-dir
Section titled “--test-dir”-t, --test-dir <TEST_DIR>
Read the test cases in this folder instead of the testConfigs of sgconfig.yml.
--snapshot-dir
Section titled “--snapshot-dir”--snapshot-dir <SNAPSHOT_DIR>
The snapshot folder inside the test folder.
Default: __snapshots__.
--filter
Section titled “--filter”-f, --filter <FILTER>
Test only the rules whose id matches this regular expression.
--skip-snapshot-tests
Section titled “--skip-snapshot-tests”--skip-snapshot-tests
Check only the valid and invalid examples, and no snapshot.
Cannot be combined with --update-all, --interactive.
--update-all
Section titled “--update-all”-U, --update-all
Accept every changed snapshot and write it.
--interactive
Section titled “--interactive”-i, --interactive
Ask about each changed snapshot before writing it.
Cannot be combined with --format.
--format
Section titled “--format”--format <FORMAT>
Print text, or JSON with each case's id, source and status and the failed count.
Default: text.
Values: text, json.
Examples
Section titled “Examples”xpd new makes the project, the rule and an empty test file.
$ 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.
id: team/no-printvalid: - "log(1)"invalid: - "import team\nprint(1)"$ xpd testteam/no-print: passedteam/no-print: snapshot mismatch2 cases, 1 failed$ xpd test -Uteam/no-print: passedteam/no-print: updated2 cases, 0 failed--format json prints each case with its id, source and status, and the failed count.
Exit status
Section titled “Exit status”| 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 |