{"id":16329101,"url":"https://github.com/PanAeon/vscode-tmgrammar-test","last_synced_at":"2025-10-25T21:31:03.579Z","repository":{"id":34885513,"uuid":"186869645","full_name":"PanAeon/vscode-tmgrammar-test","owner":"PanAeon","description":"Test helpers for VSCode textmate grammars ","archived":false,"fork":false,"pushed_at":"2025-01-13T03:49:52.000Z","size":9367,"stargazers_count":99,"open_issues_count":5,"forks_count":13,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-01-13T04:28:35.657Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/PanAeon.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-05-15T17:01:53.000Z","updated_at":"2025-01-13T03:49:57.000Z","dependencies_parsed_at":"2023-01-15T10:00:53.173Z","dependency_job_id":"cc33fd66-d39e-4015-b8f1-b9bf9c9119a4","html_url":"https://github.com/PanAeon/vscode-tmgrammar-test","commit_stats":{"total_commits":74,"total_committers":9,"mean_commits":8.222222222222221,"dds":"0.29729729729729726","last_synced_commit":"7007d551e29ec5967bafc5a5d7be8e6d7b5e8db4"},"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PanAeon%2Fvscode-tmgrammar-test","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PanAeon%2Fvscode-tmgrammar-test/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PanAeon%2Fvscode-tmgrammar-test/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PanAeon%2Fvscode-tmgrammar-test/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/PanAeon","download_url":"https://codeload.github.com/PanAeon/vscode-tmgrammar-test/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":238212375,"owners_count":19434954,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-10T23:14:41.206Z","updated_at":"2025-10-25T21:31:01.974Z","avatar_url":"https://github.com/PanAeon.png","language":"TypeScript","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"readme":"![Node.js CI](https://img.shields.io/github/actions/workflow/status/PanAeon/vscode-tmgrammar-test/nodejs.yml?branch=master\u0026style=for-the-badge) ![NPM Version](https://img.shields.io/npm/v/vscode-tmgrammar-test?style=for-the-badge)\n## VSCode Textmate grammar test\n\n\nProvides a way to test textmate grammars against a vscode engine using user-friendly plaintext files.\n\nDemo:\n\n[![asciicast](https://asciinema.org/a/QoGS5fPsxDOHl1T43zzmFxJAU.svg)](https://asciinema.org/a/QoGS5fPsxDOHl1T43zzmFxJAU)\n\nInspired by [Sublime Text syntax tests](https://www.sublimetext.com/docs/3/syntax.html#testing)\n\n\n### Installation\n\nAs a project dependency:\n\n```bash\nnpm i --save-dev vscode-tmgrammar-test\n```\n\nOr as a standalone command line tool:\n\n```bash\nnpm i -g vscode-tmgrammar-test\nvscode-tmgrammar-test --help\n```\n\n\n### Unit tests\n\n```scala\n// SYNTAX TEST \"source.scala\" \"sample testcase\"\n\n// line can start with a \u003ccomment token\u003e and not have a valid assertion\n\nclass Stack[A] {\n// \u003c-----  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\nTo write a unit test:\n\n* include a header line:\n\n```\n\u003ccomment token\u003e SYNTAX TEST \"\u003clanguage scope\u003e\" \"optional description\"\n```\n\n* Require tokens to have specific scope by using `^`\u0026nbsp;\u0026nbsp;:\n\n```scala\nprivate var elements: List[A] = Nil\n//          ^^^^^^^^ variable.other.declaration.scala\n```\n\n* Get into those pesky first few characters by using `\u003c-`:\n\n```scala\nvar x = 3\n// \u003c--- keyword.declaration.volatile.scala\n//  the length of '-' determine how many characters are matched from the start of the line\nx=5\n//  \u003c~- keyword.operator.comparison.scala\n//  you specify offset from start by using '~' character, just in case\n```\n\n* To ensure that tokens **don't** have undesired scopes put `-` symbol before them:\n```scala\n  / ensure comment start with two double slashes\n  ^ - comment.line.double slash.scala\n\n  / or you can combine both positive and negative scopes\n  ^ source.scala - comment.line.double slash.scala\n```\n\nLines which start with a `\u003ccomment token\u003e` and assertion symbol are ignored by the textmate grammar.\n\n\nNote, that scope comparison takes into account relative scope's position.\nSo, if required scopes are `'scope1 scope2'`, the test will report an error if a grammar returns them as `'scope2 scope1'`.\n\nTo run a unit test:\n```bash\nvscode-tmgrammar-test 'tests/unit/**/*.test.scala'\n```\n\n\n### Snapshot tests\nSnapshot tests are like `functional tests` but you don't have to write outputs explicitly.\nAll you have to do is to provide a source files, scopes of which you want to test. Then on\nthe first run `vscode-tmgrammar-snap` will generate a set of `.snap` files which are an\ninstant snapshot of lines of the source files together with corresponding scopes.\n\nThen if you change the grammar and run the test again, the program will output the changes between\nthe `.snap` file and the real output.\nIf you satisfied with the changes you can `commit` them by running\n```bash\nvscode-tmgrammar-snap --updateSnapshot .... \n```\nthis will overwrite the existing `.snap` files with a new ones.\nAfter this you should commit them alongside with the source code test cases.\n\nYou can read more about them at [snapshot testing](https://jestjs.io/docs/en/snapshot-testing)\n\nTo run snapshot test:\n```bash\nvscode-tmgrammar-snap 'tests/snap/**/*.scala'\n```\n\n### Language configuration via package.json\n\nThe configuration follows the format of vscode:\n\n```json\n{\n    \"contributes\": {\n        \"languages\": [\n            {\n                \"id\": \"scala\",\n                \"extensions\": [\n                    \".scala\",\n                    \".sbt\",\n                    \".sc\"\n                ]\n            }\n        ],\n        \"grammars\": [\n            {\n                \"language\": \"scala\",\n                \"scopeName\": \"source.scala\",\n                \"path\": \"./syntaxes/Scala.tmLanguage.json\"\n            }\n        ]\n    }\n}\n```\nThe idea is that for the average language extension all necessary information for tests are already included in the `package.json`.\nIt is optional, though. If the configuration is missing it is necessary to specify grammars and scopeName of testcases via command line options.\n\nRight now only regular grammars and *Injection Grammars* via `injectTo` directive are supported.\n\n\n### Command Line Options\n\nUnit tests:\n```\nUsage: vscode-tmgrammar-test [options] \u003ctestcases...\u003e\n\nRun Textmate grammar test cases using vscode-textmate\n\nArguments:\n  testcases                      A glob pattern(s) which specifies testcases to run, e.g. \"./tests/**/test*.dhall\". Quotes are important!\n\nOptions:\n  -g, --grammar \u003cgrammar\u003e          Path to a grammar file. Multiple options supported. 'scopeName' is taken from the grammar (default: [])\n  --config \u003cconfiguration.json\u003e    Path to the language configuration, package.json by default\n  -c, --compact                    Display output in the compact format, which is easier to use with VSCode problem matchers\n  --xunit-report \u003creport.xml\u003e      Path to directory where test reports in the XUnit format will\n                                   be emitted in addition to console output\n  --xunit-format \u003cgeneric|gitlab\u003e  Format of XML reports generated when --xunit-report is used.\n                                   `gitlab` format is suitable for viewing the results in GitLab\n  -V, --version                    output the version number\n  -h, --help                       display help for command\n```\n\nSnapshot tests:\n```\nUsage: vscode-tmgrammar-snap [options] \u003ctestcases...\u003e\n\nRun VSCode textmate grammar snapshot tests\n\nArguments:\n  testcases                      A glob pattern(s) which specifies testcases to run, e.g. \"./tests/**/test*.dhall\". Quotes are important!\n\nOptions:\n  -u, --updateSnapshot           overwrite all snap files with new changes\n  --config \u003cconfiguration.json\u003e  Path to the language configuration, package.json by default\n  --printNotModified             include not modified scopes in the output (default: false)\n  --expandDiff                   produce each diff on two lines prefixed with \"++\" and \"--\" (default: false)\n  -g, --grammar \u003cgrammar\u003e        Path to a grammar file. Multiple options supported. 'scopeName' is taken from the grammar (default: [])\n  -s, --scope \u003cscope\u003e            Explicitly specify scope of testcases, e.g. source.dhall\n  -V, --version                  output the version number\n  -h, --help                     display help for command\n```\n\n### Setup VSCode unit test task\n\nYou can setup a vscode unit test task for convenience:\n\n```json\n        {\n            \"label\": \"Run tests\",\n            \"type\": \"shell\",\n            \"command\": \"vscode-tmgrammar-test -c -g testcase/dhall.tmLanguage.json '**/*.dhall'\",\n            \"group\": \"test\",\n            \"presentation\": {\n                \"reveal\": \"always\",\n                \"panel\":\"new\",\n            },\n            \"problemMatcher\": {\n                \"owner\": \"vscode-tmgrammar-test\",\n                \"fileLocation\": [\n                    \"relative\",\n                    \"${workspaceFolder}\",\n                ],\n                \"pattern\": [\n                    {\n                        \"regexp\": \"^(ERROR)\\\\s([^:]+):(\\\\d+):(\\\\d+):(\\\\d+)\\\\s(.*)$\",\n                        \"severity\": 1,\n                        \"file\": 2,\n                        \"line\": 3,\n                        \"column\": 4,\n                        \"endColumn\": 5,\n                        \"message\": 6,\n                    },\n                ],\n            },\n        },\n```\n\nNotice the `-c` option that will output messages in a handy format for the problemMatcher.\n\nResult:\n\n![Error in the editor](images/error.in.editor.png?raw=true \"Error in the editor\")\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FPanAeon%2Fvscode-tmgrammar-test","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FPanAeon%2Fvscode-tmgrammar-test","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FPanAeon%2Fvscode-tmgrammar-test/lists"}