{"id":15405,"library":"vscode-tmgrammar-test","title":"VSCode Textmate Grammar Test Runner","description":"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.","status":"active","version":"0.1.3","language":"javascript","source_language":"en","source_url":"https://github.com/PanAeon/vscode-tmgrammar-test","tags":["javascript","test","unit-test","textmate","grammar","visual","studio","code"],"install":[{"cmd":"npm install vscode-tmgrammar-test","lang":"bash","label":"npm"},{"cmd":"yarn add vscode-tmgrammar-test","lang":"bash","label":"yarn"},{"cmd":"pnpm add vscode-tmgrammar-test","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core runtime dependency for parsing TextMate grammars, updated to v5.4.0 in v0.0.11.","package":"vscode-textmate","optional":false}],"imports":[{"note":"Programmatic access to run unit tests. The library primarily functions as a CLI tool, but exposes these functions for more advanced integrations.","wrong":"const { runUnitTests } = require('vscode-tmgrammar-test');","symbol":"runUnitTests","correct":"import { runUnitTests } from 'vscode-tmgrammar-test';"},{"note":"Programmatic access to run snapshot tests, analogous to the CLI's snapshot functionality. Useful for custom test runners or scripts.","wrong":"const { runSnapshotTests } = require('vscode-tmgrammar-test');","symbol":"runSnapshotTests","correct":"import { runSnapshotTests } from 'vscode-tmgrammar-test';"},{"note":"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.","symbol":"CLI usage (package.json script)","correct":"\"test:grammar\": \"vscode-tmgrammar-test 'tests/unit/**/*.test.scala'\""},{"note":"For global installation (`npm i -g`), the executable `vscode-tmgrammar-test` is directly available in the PATH.","wrong":"node vscode-tmgrammar-test 'tests/snap/**/*.scala'","symbol":"CLI usage (global)","correct":"vscode-tmgrammar-test 'tests/snap/**/*.scala'"}],"quickstart":{"code":"npm i --save-dev vscode-tmgrammar-test\n\n// Create a unit test file, e.g., `tests/example.test.js`\n// This content would typically be in a `.scala` or similar file, not a `.js` file itself.\n// SYNTAX TEST \"source.scala\" \"basic scala class definition\"\n\n// line can start with a <comment token> and not have a valid assertion\n\nclass Stack[A] {\n// <-----  keyword.declaration.scala\n//   ^ - keyword.declaration.scala entity.name.class.declaration\n//    ^^^^^  entity.name.class.declaration\n//         ^  source.scala meta.bracket.scala\n//          ^  entity.name.class\n//           ^  meta.bracket.scala\n//             ^  punctuation.section.block.begin.scala\n}\n\n// Add to package.json scripts:\n// \"scripts\": {\n//   \"test:grammar\": \"vscode-tmgrammar-test 'tests/**/*.test.scala'\"\n// }\n\n// Then run from your terminal:\nnpx vscode-tmgrammar-test 'tests/**/*.test.js' # Adjust glob to your test file extension","lang":"typescript","description":"Demonstrates installation as a dev dependency and running a basic unit test for a TextMate grammar using the CLI tool."},"warnings":[{"fix":"Remove the `-t` option and pass test file paths directly, e.g., `vscode-tmgrammar-test 'path/to/tests/**/*.scala'`.","message":"The `-t` option for specifying test cases was removed. Test cases should now be specified directly as arguments without this flag.","severity":"breaking","affected_versions":">=0.1.1"},{"fix":"Remove the `--scope` option. Ensure unit test headers correctly specify the language scope, e.g., `// SYNTAX TEST \"source.scala\"`.","message":"The `--scope` option for specifying grammar scope was removed as unit tests now derive scope information from their header.","severity":"breaking","affected_versions":">=0.1.1"},{"fix":"Remove any usage of the `--validate` option from your CLI commands.","message":"The `--validate` option for grammar validation has been removed.","severity":"breaking","affected_versions":">=0.1.1"},{"fix":"Upgrade your Node.js environment to a supported version (e.g., Node.js 12 or newer).","message":"Node.js version 10.x is no longer supported.","severity":"breaking","affected_versions":">=0.1.1"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.0.11"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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.","cause":"An invalid or unsupported regex pattern was used within a look-behind assertion in a grammar.","error":"Error: Invalid pattern in look-behind assertion"},{"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.","cause":"Inconsistent handling of line endings (Windows vs. Unix) between snapshot generation and subsequent test runs.","error":"Snapshot tests fail after updating snapshots and re-running"},{"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.","cause":"Path or file system compatibility issues prevented the test runner from locating or executing tests on Windows.","error":"vscode-tmgrammar-snap doesn't run test cases on Windows"}],"ecosystem":"npm"}