VSCode Textmate Grammar Test Runner

0.1.3 · active · verified Tue Apr 21

vscode-tmgrammar-test is a utility for testing VSCode TextMate grammars using a user-friendly plaintext file format, inspired by Sublime Text's syntax testing capabilities. The package provides both unit and snapshot testing functionalities, allowing developers to verify syntax highlighting behavior against a VSCode engine. The current stable version is v0.1.3, with releases occurring periodically to introduce new features, fix bugs, and address breaking changes, such as the removal of certain CLI options and dropping Node.js 10.x support in v0.1.1. Key differentiators include its direct use of the VSCode TextMate engine for accurate simulation, a clear and concise assertion syntax within test files for precise scope checking, and built-in snapshot testing for tracking grammar changes over time. It is designed to be integrated as a development dependency, primarily invoked via its command-line interface, making it an essential tool for grammar authors.

Common errors

```
Error: Invalid pattern in look-behind assertion
```
cause An invalid or unsupported regex pattern was used within a look-behind assertion in a grammar.

fix Update `vscode-tmgrammar-test` to v0.0.11 or newer to fix the issue with updated `vscode-textmate` and `oniguruma` which resolves certain invalid pattern errors.
```
Snapshot tests fail after updating snapshots and re-running
```
cause Inconsistent handling of line endings (Windows vs. Unix) between snapshot generation and subsequent test runs.

fix Update `vscode-tmgrammar-test` to v0.0.7 or newer. This version introduced logic to handle both Windows and Unix line endings consistently across platforms.
```
vscode-tmgrammar-snap doesn't run test cases on Windows
```
cause Path or file system compatibility issues prevented the test runner from locating or executing tests on Windows.

fix Update `vscode-tmgrammar-test` to v0.0.6 or newer. This version includes specific fixes to ensure test cases run correctly on Windows operating systems.

Warnings

breaking The `-t` option for specifying test cases was removed. Test cases should now be specified directly as arguments without this flag.
Fix: Remove the `-t` option and pass test file paths directly, e.g., `vscode-tmgrammar-test 'path/to/tests/**/*.scala'`.
breaking The `--scope` option for specifying grammar scope was removed as unit tests now derive scope information from their header.
Fix: Remove the `--scope` option. Ensure unit test headers correctly specify the language scope, e.g., `// SYNTAX TEST "source.scala"`.
breaking The `--validate` option for grammar validation has been removed.
Fix: Remove any usage of the `--validate` option from your CLI commands.
breaking Node.js version 10.x is no longer supported.
Fix: Upgrade your Node.js environment to a supported version (e.g., Node.js 12 or newer).
gotcha The behavior with Unicode symbols may have changed due to an update to the `oniguruma` regex engine (bumped in `vscode-textmate`). This change is intended to be consistent with VSCode's behavior.
Fix: If encountering unexpected behavior with Unicode, re-evaluate test cases, especially those with complex regex patterns involving Unicode characters, and ensure they align with the updated VSCode/Oniguruma behavior.

Install

npm install vscode-tmgrammar-test npm
yarn add vscode-tmgrammar-test yarn
pnpm add vscode-tmgrammar-test pnpm

Imports

runUnitTests
wrong:
```
const { runUnitTests } = require('vscode-tmgrammar-test');
```
correct:
```
import { runUnitTests } from 'vscode-tmgrammar-test';
```
Programmatic access to run unit tests. The library primarily functions as a CLI tool, but exposes these functions for more advanced integrations.
runSnapshotTests
wrong:
```
const { runSnapshotTests } = require('vscode-tmgrammar-test');
```
correct:
```
import { runSnapshotTests } from 'vscode-tmgrammar-test';
```
Programmatic access to run snapshot tests, analogous to the CLI's snapshot functionality. Useful for custom test runners or scripts.
CLI usage (package.json script)
```
"test:grammar": "vscode-tmgrammar-test 'tests/unit/**/*.test.scala'"
```
The most common way developers use this tool is via a package.json script to invoke the CLI. Ensure the package is installed as a dev dependency.
CLI usage (global)
wrong:
```
node vscode-tmgrammar-test 'tests/snap/**/*.scala'
```
correct:
```
vscode-tmgrammar-test 'tests/snap/**/*.scala'
```
For global installation (`npm i -g`), the executable `vscode-tmgrammar-test` is directly available in the PATH.

Quickstart

Demonstrates installation as a dev dependency and running a basic unit test for a TextMate grammar using the CLI tool.

npm i --save-dev vscode-tmgrammar-test

// Create a unit test file, e.g., `tests/example.test.js`
// This content would typically be in a `.scala` or similar file, not a `.js` file itself.
// SYNTAX TEST "source.scala" "basic scala class definition"

// line can start with a <comment token> and not have a valid assertion

class Stack[A] {
// <-----  keyword.declaration.scala
//   ^ - keyword.declaration.scala entity.name.class.declaration
//    ^^^^^  entity.name.class.declaration
//         ^  source.scala meta.bracket.scala
//          ^  entity.name.class
//           ^  meta.bracket.scala
//             ^  punctuation.section.block.begin.scala
}

// Add to package.json scripts:
// "scripts": {
//   "test:grammar": "vscode-tmgrammar-test 'tests/**/*.test.scala'"
// }

// Then run from your terminal:
npx vscode-tmgrammar-test 'tests/**/*.test.js' # Adjust glob to your test file extension

view raw JSON →