README
gherking
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
Usage
'use strict';
const compiler = require('gherking');
const Replacer = require('gpc-replacer');
let ast = await compiler.load('./features/src/login.feature');
ast = compiler.process(
ast,
new Replacer({
name: 'Hello'
})
);
await compiler.save('./features/dist/login.feature', ast, {
lineBreak: '\r\n'
});
'use strict';
import {load, process, save} from "gherking";
import Replacer = require("gpc-replacer");
let ast = await load("./features/src/login.feature");
ast = process(
ast,
new Replacer({
name: 'Hello'
})
);
await save('./features/dist/login.feature', ast, {
lineBreak: '\r\n'
});
Pre-compilers
- ForLoop - Enables the user to loop scenarios and scenario outlines in order to repeat them.
- Macro - Enables the user to create and execute macros.
- RemoveDuplicates - Removes duplicated tags or example data table rows.
- Replacer - Replaces keywords in the feature files.
- ScenarioNumbering - Adds an index to all scenario and scenario outline's name.
- ScenarioOutlineExpander - Expand the Scenario Outlines to actual scenarios.
- ScenarioOutlineNumbering - Makes all scenario, generated from scenario outlines unique.
- StepGroups - Corrects the gherkin keywords of steps to make the tests more readable.
CLI
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
Arguments
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 that need to be
precompiled. [string]
-b, --base The base directory of feature files. [string]
-d, --destination The destination directory of precompiled feature files.
[string]
--verbose [boolean]
--clean Whether the destination directory should be clean in
advance. [boolean]
--help Show help [boolean]
Important
config
is a mandatory option since that is the only way to specify the precompilers- either a source directory or base directory must be specified either by command line or by configuration
- if one of the location configurations is missing, it is set based on the given other locations, for example
- if only
base: "e2e/features"
set, thensource
will bee2e/features/**/*.feature
anddestination
will bee2e/features/dist
- if only
source
directory is set, thenbase
will be the source directory,destination
will be{source}/dist
andsource
will be modified to a glob pattern:{source}/**/*.feature
- if only
Configuration
The configuration must contain the precompilers configuration and optionally all options which command-line arguments could specify. It can be a JSON file or a JS file
// .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 formatting options for
// gherkin-formatter, see documentation for more info:
// https://github.com/gherking/gherkin-formatter
"formatOptions": {
"compact": true
}
}
Note: command line arguments should also support setting formatOptions
, via object arguments, see Object@yargs.
API
load
It loads the given feature file to a GherkinDocument
.
Params:
{string} pathToFile
- the path of the feature file which needs to be loaded
Returns: {Promise<Document[]>}
the AST of the given feature file
save
Saves the given AST as a feature file to the given path.
Params:
{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{Document|Document[]} ast
- the AST needs to be saved to the file{FormatterOptions} [options]
- configuration of formatting, see FormatterConfig
process
Applies the given precompilers to the given AST.
Params:
{Document|Document[]} ast
- the AST needs to be processed{...PreCompiler} pre-compilers
- the pre-compilers needs to be applied to the given AST
Returns: {Document[]}
the processed AST
PreCompiler
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.
Event 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:
- onFeature1
- onRule1
- onScenario1
- onScenarioOutline1
- onBackground
- onExamples1
- onStep1
- onTag1
- onDocString
- onDataTable
- onTableRow1
If the method returns
null
, then the given element will be deleted- an element, then the original element will be replaced with the returned one
- (only for 1) 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
- nothing, the element won't be replaced
Filter methods
Every 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:
- preFeature, postFeature
- preRule, postRule
- preScenario, postScenario
- preScenarioOutline, postScenarioOutline
- preBackground, postBackground
- preExamples, postExamples
- preStep, postStep
- preTag, postTag
- preDocString, postDocString
- preDataTable, postDataTable
- preTableRow, postTableRow
Other
This package uses debug for logging, use gherking
:
DEBUG=gherking* gherking ...
For detailed documentation see the TypeDocs documentation.