{"id":15470453,"url":"https://github.com/gherking/gherking","last_synced_at":"2025-08-21T17:31:47.184Z","repository":{"id":37706284,"uuid":"87965612","full_name":"gherking/gherking","owner":"gherking","description":"GherKing is a tool to make Gherkin smarter! It allows you to handle Cucumber/Gherkin feature files programmatically, in your JavaScript/TypeScript code.","archived":false,"fork":false,"pushed_at":"2024-11-20T04:32:18.000Z","size":1189,"stargazers_count":13,"open_issues_count":16,"forks_count":2,"subscribers_count":6,"default_branch":"main","last_synced_at":"2024-12-08T04:05:57.609Z","etag":null,"topics":["cli","cucumber","feature-file","gherkin","gherking","hacktoberfest","typescript"],"latest_commit_sha":null,"homepage":"https://gherking.github.io/gherking/","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/gherking.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","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":"2017-04-11T18:17:21.000Z","updated_at":"2024-11-20T04:31:58.000Z","dependencies_parsed_at":"2024-01-12T22:09:56.868Z","dependency_job_id":"5368c42b-1c77-48a6-b2f5-ea677d70c231","html_url":"https://github.com/gherking/gherking","commit_stats":{"total_commits":56,"total_committers":4,"mean_commits":14.0,"dds":0.5,"last_synced_commit":"c00ab574d45db44156a927280820b53238e1beba"},"previous_names":["judit-nahaj/gherkin-precompiler"],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gherking%2Fgherking","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gherking%2Fgherking/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gherking%2Fgherking/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gherking%2Fgherking/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gherking","download_url":"https://codeload.github.com/gherking/gherking/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":230523761,"owners_count":18239445,"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":["cli","cucumber","feature-file","gherkin","gherking","hacktoberfest","typescript"],"created_at":"2024-10-02T02:04:45.984Z","updated_at":"2024-12-20T02:06:35.760Z","avatar_url":"https://github.com/gherking.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# gherking\n\n![Downloads](https://img.shields.io/npm/dw/gherking?style=flat-square) ![Version@npm](https://img.shields.io/npm/v/gherking?label=version%40npm\u0026style=flat-square) ![Version@git](https://img.shields.io/github/package-json/v/gherking/gherking/master?label=version%40git\u0026style=flat-square) ![CI](https://img.shields.io/github/actions/workflow/status/gherking/gherking/ci.yml?branch=master\u0026label=ci\u0026style=flat-square) ![Docs](https://img.shields.io/github/actions/workflow/status/gherking/gherking/docs.yml?branch=master\u0026label=docs\u0026style=flat-square)\n\n\u003e **IMPORTANT** The `gherking` package - and the `gpc-*` ones - are placements of the original `gherkin-precompiler` package and are not compatible with any code written in it because of the changed API.\n\nGherKing is a tool to make Gherkin smarter! It allows you to handle Cucumber/Gherkin feature files programmatically in your JavaScript/TypeScript code.\n\nIt is based on the AST what is provided by [gherkin-ast](https://www.npmjs.com/package/gherkin-ast)\n\n## Usage\n\n```javascript\nconst compiler = require('gherking');\nconst Replacer = require('gpc-replacer');\n\nlet ast = await compiler.load('./features/src/login.feature');\nast = await compiler.process(\n    ast,\n    new Replacer({\n        name: 'Hello'\n    })\n);\nawait compiler.save('./features/dist/login.feature', ast, {\n    lineBreak: '\\r\\n'\n});\n```\n\n```typescript\nimport {load, process, save} from \"gherking\";\nimport Replacer = require(\"gpc-replacer\");\n\nlet ast = await load(\"./features/src/login.feature\");\nast = await process(\n    ast,\n    new Replacer({\n        name: 'Hello'\n    })\n);\nawait save('./features/dist/login.feature', ast, {\n    lineBreak: '\\r\\n'\n});\n```\n\n### Pre-compilers\n\nSome of our base precompilers:\n\n * [Filter](https://www.npmjs.com/package/gpc-filter) - Enables the user to filter out scenarios, based on cucumber-tag-expressions.\n * [ForLoop](https://www.npmjs.com/package/gpc-for-loop) - Enables the user to loop scenarios and scenario outlines in order to repeat them.\n * [Macro](https://www.npmjs.com/package/gpc-macro) - Enables the user to create and execute macros.\n * [RemoveDuplicates](https://www.npmjs.com/package/gpc-remove-duplicates) - Removes duplicated tags or example data table rows.\n * [Replacer](https://www.npmjs.com/package/gpc-replacer) - Replaces keywords in the feature files.\n * [ScenarioNumbering](https://www.npmjs.com/package/gpc-scenario-numbering) - Adds an index to all scenario and scenario outline's name.\n * [ScenarioOutlineExpander](https://www.npmjs.com/package/gpc-scenario-outline-expander) - Expand the Scenario Outlines to actual scenarios.\n * [ScenarioOutlineNumbering](https://www.npmjs.com/package/gpc-scenario-outline-numbering) - Makes all scenario, generated from scenario outlines unique.\n * [StepGroups](https://www.npmjs.com/package/gpc-step-groups) - Corrects the gherkin keywords of steps to make the tests more readable.\n\nYou can find all our precompilers [in this list](https://github.com/search?q=topic%3Agpc+org%3Agherking\u0026type=Repositories) or on our [home page](https://gherking.github.io/).\n\n## CLI\n\nThe package provides a command-line interface to precompile feature files easily.\n\n```bash\n# install package globally\nnpm install -g gherking\n\n# use gherking, precompile or gherkin-precompiler commands\ngherking --config .gherking.json --base e2e/features/src --destination e2e/features/dist\n```\n\n### Arguments\n\n```shell\nUsage: gherking --config \u003cpath\u003e [options]\n\nOptions:\n      --version      Show version number                               [boolean]\n  -c, --config       The path of the configuration file which contains the\n                     precompilers and their configurations.\n                                          [string] [default: \"./.gherking.json\"]\n  -s, --source       The pattern or path of feature files which needs to be\n                     precompiled.                                       [string]\n  -b, --base         The base directory of feature files.               [string]\n  -d, --destination  The destination directory of precompiled feature files.\n                                                                        [string]\n      --install      Whether the missing precompilers (gpc-* packages) should be\n                     installed and save to the package.json. Packages will be\n                     installed in the current folder, and package.json created\n                     if it is not there yet.          [boolean] [default: false]\n      --verbose      Whether some information should be displayed on the screen.\n                                                      [boolean] [default: false]\n      --clean        Whether the destination directory should be clean in\n                     advance.                         [boolean] [default: false]\n      --help         Show help                                         [boolean]\n\n```\n\n#### Important\n\n* `config` is a mandatory option since that is the only way to specify the precompilers\n* either a **source directory** or **base directory** must be specified either by command line or by configuration\n* if one of the location configurations is missing, it is set based on the given other locations, for example\n  + if only `base: \"e2e/features\"` set, then `source` will be `e2e/features/**/*.feature` and `destination` will be `e2e/features/dist`\n  + if only `source` directory is set, then `base` will be the source directory,  `destination` will be `{source}/dist` and `source` will be modified to a glob pattern: `{source}/**/*.feature`\n* the feature of installing the missing packages relies on the NPM used on the execution platform, thus whether the installed package is added to the package.json or not, depends on it\n\n### Configuration\n\nThe configuration **must** contain the precompilers configuration and optionally all options that command-line arguments could specify. It can be a JSON file or a JS file.\n\n\u003e The configuration should be recognized by most of the IDE (as GherKing is added to the [schemastore](http://schemastore.org/)).\n\u003e  - IntelliJ Idea, WebStorm, etc: \u003chttps://www.jetbrains.com/help/webstorm/json.html#ws_json_using_schemas\u003e\n\u003e  - VSCode: use the following plugin: \u003chttps://marketplace.visualstudio.com/items?itemName=remcohaszing.schemastore\u003e\n\u003e If the schema is not recognized even after that, please update your IDE or add the `$schema` key to the configuration:\n\u003e ```js\n\u003e // .gherking.json\n\u003e {\n\u003e    // you can set this schema, so that the IDE will help with the config\n\u003e    \"$schema\": \"https://gherking.github.io/gherking/gherking.schema.json\",\n\u003e   // ...\n\u003e }\n\u003e ```\n\n```js\n// .gherking.json\n{\n    // compilers should be an array of precompiler configurations\n    \"compilers\": [\n        // one option is to use precompiler packages,\n        {\n            // by setting the package\n            \"path\": \"gpc-replacer\",\n            // any by setting the configuration which\n            // is passed to the constructor\n            \"configuration\": {\n                \"user\": \"ta.user1@example.com\"\n            }\n        },\n        // other option is to set precompiler object\n        {\n            // by setting the path to the JS file\n            \"path\": \"e2e/utils/myCompiler.js\"\n        }\n    ],\n    // source can also be set here\n    \"source\": \"e2e/features/src/**/*.feature\",\n    // base can also be set here\n    \"base\": \"e2e/features/src\",\n    // destination can also be set here\n    \"destination\": \"e2e/features/dist\",\n    // Config file can contain parsing options for\n    // gherkin-ast, see documentation for more info:\n    // https://github.com/gherking/gherkin-ast\n    \"parseConfig\": {\n        \"tagFormat\": \"functional\"    \n    }  \n    // Config file can contain formatting options for\n    // gherkin-formatter, see documentation for more info:\n    // https://github.com/gherking/gherkin-formatter\n    \"formatOptions\": {\n        \"compact\": true,\n        \"tagFormat\": \"assignment\"\n    }\n}\n```\n\nNote: command line arguments should also support setting `formatOptions` , via object arguments, see [Object@yargs](https://github.com/yargs/yargs/blob/main/docs/tricks.md#objects).\n\n\u003c!--\n## API\n\n### `load`\n\nIt loads the given feature file to a `GherkinDocument` .\n\n**Params:**\n\n * `{string} pathToFile` - the path of the feature file which needs to be loaded\n \n**Returns:** `{Promise\u003cDocument[]\u003e}` the AST of the given feature file\n\n### `save`\n\nSaves the given AST as a feature file to the given path.\n\n**Params:**\n \n * `{string|PathGenerator} pathToFile` - the path of the feature file where the AST needs to be saved, or a function that can generate the path from the AST and the index\n * `{Document|Document[]} ast` - the AST needs to be saved to the file\n * `{FormatterOptions} [options]` - configuration of formatting, see [FormatterConfig](https://github.com/gherking/gherkin-formatter)\n \n\n### `process`\n\nApplies the given precompilers to the given AST.\n\n**Params:**\n\n * `{Document|Document[]} ast` - the AST needs to be processed\n * `{...PreCompiler} pre-compilers` - the pre-compilers needs to be applied to the given AST\n \n**Returns:** `{Promise\u003cDocument[]\u003e}` the processed AST\n--\u003e\n\n## PreCompiler\n\nIf you want to create your precompiler, you only have to extend the `Default` class and override the filter and event methods you want to use; or create an object with the desired methods.\n\n### Event methods\n\nEvery element can be modified by using its correspondent event methods.\n\nAll event methods (except `onFeature` ) receives the given element, its parent, and - if applicable - the index of the element.\nGiven that all events receive the given element as an `Object` , they can be easily modified by modifying the object itself.\n\nThe following methods are available, to see exact signature of the given method, click on the name of it:\n\n * [onDocument](src/PreCompiler.ts#L23)\n * [onFeature](src/PreCompiler.ts#L24)\u003csup\u003e1\u003c/sup\u003e\n * [onRule](src/PreCompiler.ts#L25)\u003csup\u003e1\u003c/sup\u003e\n * [onScenario](src/PreCompiler.ts#L26)\u003csup\u003e1\u003c/sup\u003e\n * [onScenarioOutline](src/PreCompiler.ts#L27)\u003csup\u003e1\u003c/sup\u003e\n * [onBackground](src/PreCompiler.ts#L28)\n * [onExamples](src/PreCompiler.ts#L29)\u003csup\u003e1\u003c/sup\u003e\n * [onStep](src/PreCompiler.ts#L30)\u003csup\u003e1\u003c/sup\u003e\n * [onTag](src/PreCompiler.ts#L31)\u003csup\u003e1\u003c/sup\u003e\n * [onDocString](src/PreCompiler.ts#L32)\n * [onDataTable](src/PreCompiler.ts#L33)\n * [onTableRow](src/PreCompiler.ts#L34)\u003csup\u003e1\u003c/sup\u003e\n\nIf the method returns\n * `null` , then the given element will be deleted\n * an element, then the original element will be replaced with the returned one\n * (only for \u003csup\u003e1\u003c/sup\u003e) an element array, in case of an event which process list element (i.e., tag, scenario, examples, step, background, scenario outline), then the original element will be replaced with the returned list\n * nothing, the element won't be replaced\n\n### Filter methods\n\nEvery element (both single and list) in the AST can be filtered using its correspondent pre- or post filter methods.\nA pre-filter method is applied before processing the event; the post is applied after it.\n\nAll filter methods receive the given element, its parent, and - if applicable - the element's index.\nIf a filter method is set, the method **must** return `true` if the element should be kept; otherwise, the element will be discarded. If a filter method is not set, no filtering will happen on the given type of element.\n\nThe following methods are available, to see exact signature of the given method, click on the name of it:\n\n * [preFeature](src/PreCompiler.ts#L36), [postFeature](src/PreCompiler.ts#L37)\n * [preRule](src/PreCompiler.ts#L38), [postRule](src/PreCompiler.ts#L39)\n * [preScenario](src/PreCompiler.ts#L40), [postScenario](src/PreCompiler.ts#L41)\n * [preScenarioOutline](src/PreCompiler.ts#L42), [postScenarioOutline](src/PreCompiler.ts#L43)\n * [preBackground](src/PreCompiler.ts#L44), [postBackground](src/PreCompiler.ts#L45)\n * [preExamples](src/PreCompiler.ts#L46), [postExamples](src/PreCompiler.ts#L47)\n * [preStep](src/PreCompiler.ts#L48), [postStep](src/PreCompiler.ts#L49)\n * [preTag](src/PreCompiler.ts#L50), [postTag](src/PreCompiler.ts#L51)\n * [preDocString](src/PreCompiler.ts#L52), [postDocString](src/PreCompiler.ts#L53)\n * [preDataTable](src/PreCompiler.ts#L54), [postDataTable](src/PreCompiler.ts#L55)\n * [preTableRow](src/PreCompiler.ts#L56), [postTableRow](src/PreCompiler.ts#L57)\n\n### Comments\n\nThe semantic comments in the Gerhkin AST do not have their event and filter methods in Gherking because of their various types. You can use the respective owner object methods (e.g., to work with a Feature's comments, use `onFeature` to access them).\n\n## Other\n\nThis package uses [debug](https://www.npmjs.com/package/debug) for logging, use `gherking` :\n\n```shell\nDEBUG=gherking* gherking ...\n```\n\nFor detailed documentation see the [TypeDocs documentation](https://gherking.github.io/gherking/).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgherking%2Fgherking","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgherking%2Fgherking","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgherking%2Fgherking/lists"}