TextMate Grammar Test Runner

0.6.0 · active · verified Tue Apr 21

This package provides a comprehensive test runner for validating TextMate grammars against the same engine used by VS Code. It offers both unit and snapshot testing capabilities, enabling developers to write assertions against token scopes and to easily track changes in grammar tokenization over time. The current stable version is 0.6.0, with minor releases occurring relatively frequently, driven by performance improvements, bug fixes, and feature enhancements. It serves as a modern and actively maintained successor to the `vscode-tmgrammar-test` package, featuring an updated codebase and enhanced functionality. Key differentiators include its direct validation against the VS Code TextMate engine, robust snapshot testing with an update mechanism, and detailed unit testing syntax for precise scope assertions, including negative assertions and line start token targeting.

Common errors

```
Command 'textmate-grammar-test' not found
```
cause The package is not installed as a local dependency or `npx` is not being used to invoke the command.

fix Ensure `textmate-grammar-test` is listed in your `devDependencies` and run the command using `npx textmate-grammar-test` (e.g., `npx textmate-grammar-test syntax/tests/**/*.ts`) or add it to your `PATH` if globally installed (less common for dev tools).
```
Snapshot mismatch: Your snapshot tests have changed from the last run.
```
cause Your grammar's tokenization has changed, or you are migrating from an older version of `textmate-grammar-test` or `vscode-tmgrammar-test` with a different snapshot format.

fix If the changes are expected, update your snapshots by running `npx textmate-grammar-snap --updateSnapshot "tests/**/*.foo"`. If not, review your grammar changes or test files.
```
error: Tabs are not allowed in unit test files.
```
cause A unit test file contains tab characters for indentation, which is now disallowed to ensure consistent parsing and avoid ambiguity.

fix Convert all tab characters to spaces within the affected unit test file(s). Most IDEs have a 'Convert Indentation to Spaces' feature.
```
Cannot find module 'textmate-grammar-test' from 'your-test-file.js'
```
cause When attempting to use `import { ... } from 'textmate-grammar-test';` in a CommonJS environment without proper transpilation or configuration, or if the package is not installed.

fix Ensure your project is configured for ESM (e.g., `"type": "module"` in `package.json`) if using `import`, or install the package with `npm install textmate-grammar-test`.

Warnings

breaking The `--xunit-report` and `--xunit-format` CLI options were removed in version 0.5.0, impacting CI/CD setups that relied on XUnit reporting.
Fix: Migrate to alternative reporting mechanisms or update CI configurations to no longer expect XUnit output from `textmate-grammar-test`.
gotcha The `--scope` option was initially removed in v0.4.0 but subsequently re-added in v0.4.2. Users upgrading directly from versions before 0.4.2 or between 0.4.0 and 0.4.2 might encounter unexpected CLI behavior regarding scope specification.
Fix: Ensure you are on version 0.4.2 or later if you intend to use the `--scope` option. Always refer to the `--help` output for the most current options.
breaking When migrating from the deprecated `vscode-tmgrammar-test` package, snapshot format changes require a one-time update of existing `.snap` files.
Fix: After installing `textmate-grammar-test` and updating package references, run `npx textmate-grammar-snap --updateSnapshot "tests/**/*.foo"` once to conform to the new snapshot format.
gotcha Unit test files now strictly enforce space-based indentation. Using tabs within test files can lead to errors or incorrect tokenization results, as noted in changes around version 0.5.0.
Fix: Ensure all unit test `.ts` or `.js` files use spaces for indentation. Configure your editor to convert tabs to spaces for these files.
deprecated The `vscode-tmgrammar-test` and `vscode-tmgrammar-snap` packages are deprecated in favor of `textmate-grammar-test`. The new package offers an updated codebase, bug fixes, and new features.
Fix: Migrate to `textmate-grammar-test` by installing `npm i -D textmate-grammar-test` and replacing all occurrences of `vscode-tmgrammar-test` and `vscode-tmgrammar-snap` in your project.

Install

npm install textmate-grammar-test npm
yarn add textmate-grammar-test yarn
pnpm add textmate-grammar-test pnpm

Imports

runUnitTests
wrong:
```
const { runUnitTests } = require('textmate-grammar-test');
```
correct:
```
import { runUnitTests } from 'textmate-grammar-test';
```
Primarily a CLI tool, but programmatic access is available for integration. The package is ESM-first, requiring `import` syntax.
runSnapshotTests
wrong:
```
const { runSnapshotTests } = require('textmate-grammar-test');
```
correct:
```
import { runSnapshotTests } from 'textmate-grammar-test';
```
Used for programmatic execution of snapshot tests. The `textmate-grammar-snap` CLI command wraps this function.
TextMateGrammarTestCLI
```
npx textmate-grammar-test
```
The primary interaction is via the command-line interface. This 'import' refers to invoking the CLI directly, not a programmatic import.

Quickstart

Demonstrates setting up `textmate-grammar-test` in `package.json` scripts and a basic unit test file for a TypeScript grammar.

{
  "name": "my-grammar",
  "version": "1.0.0",
  "scripts": {
    "test:grammar": "npx textmate-grammar-test syntax/tests/**/*.ts"
  },
  "devDependencies": {
    "textmate-grammar-test": "^0.6.0"
  }
}

// syntax/tests/example.ts
// SYNTAX TEST "source.ts" "Basic TypeScript variable declaration"

let count: number = 1;
//  ^^^^^ variable.other.readwrite.ts
//         ^^^^^^ support.type.primitive.ts

const message = "Hello, World!";
// <---- storage.type.ts
//           ^^^^^^^ string.quoted.double.ts

view raw JSON →