IMPORTANT The
gherking
package - and thegpc-*
ones - are placements of the originalgherkin-precompiler
package and are not compatible with any code written in it because of the changed API.
GherKing is a tool to make Gherkin smarter! It allows you to handle Cucumber/Gherkin feature files programmatically in your JavaScript/TypeScript code.
It is based on the AST what is provided by gherkin-ast
const compiler = require('gherking');
const Replacer = require('gpc-replacer');
let ast = await compiler.load('./features/src/login.feature');
ast = await compiler.process(
ast,
new Replacer({
name: 'Hello'
})
);
await compiler.save('./features/dist/login.feature', ast, {
lineBreak: '\r\n'
});
import {load, process, save} from "gherking";
import Replacer = require("gpc-replacer");
let ast = await load("./features/src/login.feature");
ast = await process(
ast,
new Replacer({
name: 'Hello'
})
);
await save('./features/dist/login.feature', ast, {
lineBreak: '\r\n'
});
Some of our base precompilers:
You can find all our precompilers in this list or on our home page.
The package provides a command-line interface to precompile feature files easily.
# install package globally
npm install -g gherking
# use gherking, precompile or gherkin-precompiler commands
gherking --config .gherking.json --base e2e/features/src --destination e2e/features/dist
Usage: gherking --config <path> [options]
Options:
--version Show version number [boolean]
-c, --config The path of the configuration file which contains the
precompilers and their configurations.
[string] [default: "./.gherking.json"]
-s, --source The pattern or path of feature files which needs to be
precompiled. [string]
-b, --base The base directory of feature files. [string]
-d, --destination The destination directory of precompiled feature files.
[string]
--install Whether the missing precompilers (gpc-* packages) should be
installed and save to the package.json. Packages will be
installed in the current folder, and package.json created
if it is not there yet. [boolean] [default: false]
--verbose Whether some information should be displayed on the screen.
[boolean] [default: false]
--clean Whether the destination directory should be clean in
advance. [boolean] [default: false]
--help Show help [boolean]
config
is a mandatory option since that is the only way to specify the precompilersbase: "e2e/features"
set, then source
will be e2e/features/**/*.feature
and destination
will be e2e/features/dist
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
The 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.
The configuration should be recognized by most of the IDE (as GherKing is added to the schemastore).
- IntelliJ Idea, WebStorm, etc: https://www.jetbrains.com/help/webstorm/json.html#ws_json_using_schemas
- VSCode: use the following plugin: https://marketplace.visualstudio.com/items?itemName=remcohaszing.schemastore If the schema is not recognized even after that, please update your IDE or add the
$schema
key to the configuration:// .gherking.json
{
// you can set this schema, so that the IDE will help with the config
"$schema": "https://gherking.github.io/gherking/gherking.schema.json",
// ...
}
// .gherking.json
{
// compilers should be an array of precompiler configurations
"compilers": [
// one option is to use precompiler packages,
{
// by setting the package
"path": "gpc-replacer",
// any by setting the configuration which
// is passed to the constructor
"configuration": {
"user": "ta.user1@example.com"
}
},
// other option is to set precompiler object
{
// by setting the path to the JS file
"path": "e2e/utils/myCompiler.js"
}
],
// source can also be set here
"source": "e2e/features/src/**/*.feature",
// base can also be set here
"base": "e2e/features/src",
// destination can also be set here
"destination": "e2e/features/dist",
// Config file can contain parsing options for
// gherkin-ast, see documentation for more info:
// https://github.com/gherking/gherkin-ast
"parseConfig": {
"tagFormat": "functional"
}
// Config file can contain formatting options for
// gherkin-formatter, see documentation for more info:
// https://github.com/gherking/gherkin-formatter
"formatOptions": {
"compact": true,
"tagFormat": "assignment"
}
}
Note: command line arguments should also support setting formatOptions
, via object arguments, see Object@yargs.
If 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.
Every element can be modified by using its correspondent event methods.
All event methods (except onFeature
) receives the given element, its parent, and - if applicable - the index of the element.
Given that all events receive the given element as an Object
, they can be easily modified by modifying the object itself.
The following methods are available, to see exact signature of the given method, click on the name of it:
If the method returns
null
, then the given element will be deletedEvery element (both single and list) in the AST can be filtered using its correspondent pre- or post filter methods. A pre-filter method is applied before processing the event; the post is applied after it.
All filter methods receive the given element, its parent, and - if applicable - the element's index.
If 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.
The following methods are available, to see exact signature of the given method, click on the name of it:
The 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).
This package uses debug for logging, use gherking
:
DEBUG=gherking* gherking ...
For detailed documentation see the TypeDocs documentation.
Generated using TypeDoc