{"id":15398,"library":"textmate-grammar-test","title":"TextMate Grammar Test Runner","description":"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.","status":"active","version":"0.6.0","language":"javascript","source_language":"en","source_url":"https://github.com/serkonda7/textmate-grammar-test","tags":["javascript","test","unit-test","textmate","tmgrammar","grammar","visual","studio","code"],"install":[{"cmd":"npm install textmate-grammar-test","lang":"bash","label":"npm"},{"cmd":"yarn add textmate-grammar-test","lang":"bash","label":"yarn"},{"cmd":"pnpm add textmate-grammar-test","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Primarily a CLI tool, but programmatic access is available for integration. The package is ESM-first, requiring `import` syntax.","wrong":"const { runUnitTests } = require('textmate-grammar-test');","symbol":"runUnitTests","correct":"import { runUnitTests } from 'textmate-grammar-test';"},{"note":"Used for programmatic execution of snapshot tests. The `textmate-grammar-snap` CLI command wraps this function.","wrong":"const { runSnapshotTests } = require('textmate-grammar-test');","symbol":"runSnapshotTests","correct":"import { runSnapshotTests } from 'textmate-grammar-test';"},{"note":"The primary interaction is via the command-line interface. This 'import' refers to invoking the CLI directly, not a programmatic import.","symbol":"TextMateGrammarTestCLI","correct":"npx textmate-grammar-test"}],"quickstart":{"code":"{\n  \"name\": \"my-grammar\",\n  \"version\": \"1.0.0\",\n  \"scripts\": {\n    \"test:grammar\": \"npx textmate-grammar-test syntax/tests/**/*.ts\"\n  },\n  \"devDependencies\": {\n    \"textmate-grammar-test\": \"^0.6.0\"\n  }\n}\n\n// syntax/tests/example.ts\n// SYNTAX TEST \"source.ts\" \"Basic TypeScript variable declaration\"\n\nlet count: number = 1;\n//  ^^^^^ variable.other.readwrite.ts\n//         ^^^^^^ support.type.primitive.ts\n\nconst message = \"Hello, World!\";\n// <---- storage.type.ts\n//           ^^^^^^^ string.quoted.double.ts\n","lang":"typescript","description":"Demonstrates setting up `textmate-grammar-test` in `package.json` scripts and a basic unit test file for a TypeScript grammar."},"warnings":[{"fix":"Migrate to alternative reporting mechanisms or update CI configurations to no longer expect XUnit output from `textmate-grammar-test`.","message":"The `--xunit-report` and `--xunit-format` CLI options were removed in version 0.5.0, impacting CI/CD setups that relied on XUnit reporting.","severity":"breaking","affected_versions":">=0.5.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"0.4.0, 0.4.1"},{"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.","message":"When migrating from the deprecated `vscode-tmgrammar-test` package, snapshot format changes require a one-time update of existing `.snap` files.","severity":"breaking","affected_versions":">=0.3.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.","message":"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.","severity":"gotcha","affected_versions":">=0.5.0"},{"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.","message":"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.","severity":"deprecated","affected_versions":"<=0.3.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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).","cause":"The package is not installed as a local dependency or `npx` is not being used to invoke the command.","error":"Command 'textmate-grammar-test' not found"},{"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.","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.","error":"Snapshot mismatch: Your snapshot tests have changed from the last run."},{"fix":"Convert all tab characters to spaces within the affected unit test file(s). Most IDEs have a 'Convert Indentation to Spaces' feature.","cause":"A unit test file contains tab characters for indentation, which is now disallowed to ensure consistent parsing and avoid ambiguity.","error":"error: Tabs are not allowed in unit test files."},{"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`.","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.","error":"Cannot find module 'textmate-grammar-test' from 'your-test-file.js'"}],"ecosystem":"npm"}