{"id":14969255,"url":"https://github.com/cucumber/gherkin-utils","last_synced_at":"2025-04-07T10:29:22.277Z","repository":{"id":63653452,"uuid":"568172961","full_name":"cucumber/gherkin-utils","owner":"cucumber","description":"API for working with Gherkin documents","archived":false,"fork":false,"pushed_at":"2024-10-29T03:50:10.000Z","size":1846,"stargazers_count":12,"open_issues_count":13,"forks_count":4,"subscribers_count":11,"default_branch":"main","last_synced_at":"2024-10-29T14:46:53.382Z","etag":null,"topics":["java","javascript","polyglot-release","tidelift"],"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/cucumber.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"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},"funding":{"open_collective":"cucumber","github":"cucumber"}},"created_at":"2022-11-19T17:18:04.000Z","updated_at":"2024-10-29T03:48:52.000Z","dependencies_parsed_at":"2024-02-25T23:38:42.698Z","dependency_job_id":"ca0d50cc-b67a-4ce1-98c2-4570e5cb8585","html_url":"https://github.com/cucumber/gherkin-utils","commit_stats":{"total_commits":923,"total_committers":22,"mean_commits":41.95454545454545,"dds":0.352112676056338,"last_synced_commit":"2e26c2bf77665fd5c30427e6fb6cdc5a67b86103"},"previous_names":[],"tags_count":22,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cucumber%2Fgherkin-utils","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cucumber%2Fgherkin-utils/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cucumber%2Fgherkin-utils/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cucumber%2Fgherkin-utils/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cucumber","download_url":"https://codeload.github.com/cucumber/gherkin-utils/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247615385,"owners_count":20967184,"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":["java","javascript","polyglot-release","tidelift"],"created_at":"2024-09-24T13:41:26.837Z","updated_at":"2025-04-07T10:29:22.252Z","avatar_url":"https://github.com/cucumber.png","language":"TypeScript","funding_links":["https://opencollective.com/cucumber","https://github.com/sponsors/cucumber"],"categories":[],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/cucumber/cucumber-js/46a5a78107be27e99c6e044c69b6e8f885ce456c/docs/images/logo.svg\" alt=\"Cucumber logo\" width=\"75\"\u003e\n  \u003cbr\u003e\n  Gherkin Utils\n\u003c/h1\u003e\n\u003cp align=\"center\"\u003e\n  \u003cb\u003eUtilities for working with Gherkin documents and AST\u003c/b\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://www.npmjs.com/package/@cucumber/gherkin-utils\"\u003e\n    \u003cimg src=\"https://img.shields.io/npm/v/@cucumber/gherkin-utils.svg?color=dark-green\" alt=\"npm\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://central.sonatype.com/artifact/io.cucumber/gherkin-utils\"\u003e\n    \u003cimg src=\"https://img.shields.io/maven-central/v/io.cucumber/gherkin-utils.svg?label=Maven%20Central\u0026color=dark-green\" alt=\"maven-central\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/cucumber/gherkin-utils/actions/workflows/release-github.yaml\"\u003e\n    \u003cimg src=\"https://github.com/cucumber/gherkin-utils/actions/workflows/release-github.yaml/badge.svg\" alt=\"build\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://opencollective.com/cucumber\"\u003e\n    \u003cimg src=\"https://opencollective.com/cucumber/backers/badge.svg\" alt=\"backers\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://opencollective.com/cucumber\"\u003e\n    \u003cimg src=\"https://opencollective.com/cucumber/sponsors/badge.svg\" alt=\"sponsors\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n## Features\n\n- ✨ Formatting\n- 👉 Translation of `.feature` files to `.feature.md`\n- 🚶‍♂️ Document walker\n- 📁 Document handler\n\n## Install\n\nGherkin Utils is [available on npm](https://www.npmjs.com/package/@cucumber/gherkin-utils) for JavaScript:\n\n```console\nnpm install @cucumber/gherkin-utils\n```\n\nGherkin Utils is [available on Maven Central](https://central.sonatype.com/artifact/io.cucumber/gherkin-utils) for Java, by adding the dependency to your `pom.xml`:\n\n```xml\n\u003cdependencies\u003e\n  \u003cdependency\u003e\n    \u003cgroupId\u003eio.cucumber\u003c/groupId\u003e\n    \u003cartifactId\u003egherkin-utils\u003c/artifactId\u003e\n    \u003cversion\u003e9.0.0\u003c/version\u003e\n  \u003c/dependency\u003e\n\u003c/dependencies\u003e\n```\n\n## Usage\n\n### Command line\n\nTo run Gherkin Utils as a formatter, try any of the following:\n\n```bash\n# Format `file.feature`\n\u003e npx @cucumber/gherkin-utils format features/file.feature\n# Format `file.feature` and `other.feature`\n\u003e npx @cucumber/gherkin-utils format features/file.feature features/other.feature\n# Format feature files directly within `features/`\n\u003e npx @cucumber/gherkin-utils format features/*.feature\n# Format feature files ending with `_test.feature` in `features`\n\u003e npx @cucumber/gherkin-utils format features/*_test.feature\n# Format feature files within immediate subdirectories of `features/`\n\u003e npx @cucumber/gherkin-utils format features/**/*.feature\n```\n\nTo convert gherkin feature files to [Markdown with Gherkin](https://github.com/cucumber/gherkin/blob/04da83056751a1d4519d3886448e6fd0a6544fe1/MARKDOWN_WITH_GHERKIN.md) - or the other way around - while formatting, try the following:\n\n```bash\n# Format `file.feature` to gherkin markdown `file.feature.md`\nnpx @cucumber/gherkin-utils format --to-syntax=markdown features/file.feature\n# Format `file.feature.md` to gherkin `file.feature`\nnpx @cucumber/gherkin-utils format --to-syntax=gherkin features/file.feature.md\n```\n\nFor more details on usage, see the help menu.\n\n```bash\nnpx @cucumber/gherkin-utils --help\n```\n\n### Library\n\nThis module can also be used as a library. It provides two main utilities, `pretty` and `gherkinDocumentWalker`.\n\n#### pretty(gherkinDocument: messages.GherkinDocument, syntax: 'gherkin' | 'markdown')\n\nThis function takes a GherkinDocument as input and returns a pretty-printed representation in Gherkin or Markdown.\n\n```javascript\nimport { AstBuilder, GherkinClassicTokenMatcher, Parser } from '@cucumber/gherkin'\nimport { pretty } from '@cucumber/gherkin-utils'\nimport { IdGenerator } from '@cucumber/messages'\n\nconst uuidFn = IdGenerator.uuid()\n\nconst builder = new AstBuilder(uuidFn)\nconst matcher = new GherkinClassicTokenMatcher()\nconst parser = new Parser(builder, matcher)\n\nconst feature = `Feature:\nScenario:\nGiven step text`\n\nconst gherkinDocument = parser.parse(feature)\n\nconst formattedGherkinFeature = pretty(gherkinDocument)\n/*\nFeature:\n\n  Scenario:\n    Given step text\n\n*/\nconst formattedGherkinMarkdownFeature = pretty(gherkinDocument, 'markdown')\n/*\n# Feature:\n\n## Scenario:\n* Given step text\n\n*/\n```\n\n#### GherkinDocumentWalker class\n\nThe GherkinDocumentWalker is a class for walking and filtering the AST produced by Gherkin after parsing a feature file.\nWhen running `walkGherkinDocument` on a GherkinDocument, it will produce a deep copy of the object.\n\nIt takes two arguments upon creation:\n\n- filters: set of functions used to know if the walked elements are kept in the result. By default, all elements are kept.\n- handlers: set of function that can be used to alter the produced elements.\n\nFiltering keeps the meaning of the original GherkinDocument, which means:\n\n- if a `Background` was present, it will always be in the `Feature` (or `Rule`)\n- the kept scenarios will have the same steps and examples than the original\n\nBy default, all elements are accepted, which means that if you want to do filtering you should reject all other elements. To ease this, we also provide the `rejectAllFilters`.\n\nHere's an example:\n\n```typescript\nimport { GherkinDocumentWalker, rejectAllFilters } from '@cucumber/gherkin-utils';\n\n// Only keeps scenarios which name include 'magic'\nconst filter = new GherkinDocumentWalker({\n  ...rejectAllFilters,\n  ...{ acceptScenario: (scenario) =\u003e scenario.name.includes('magic') },\n})\n\n// Makes a list with all the scenario names\nconst allScenarioNames: string[] = []\nconst scenarioNameFinder = new GherkinDocumentWalker({}, {\n  handleScenario: (scenario) =\u003e allScenarioNames.push(scenario.name),\n})\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcucumber%2Fgherkin-utils","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcucumber%2Fgherkin-utils","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcucumber%2Fgherkin-utils/lists"}