apigeek-dialect

A library for parsing and executing Gherkin-English

Dialect features are written in "natural language" so every stakeholder can make sense of them.

It is a core dependency for the following ApiGeek projects:

ApiGeek-Architect - an automation and orchestration tool for Software Architects

ApiGeek-Affirm - a BDD test tool for Software Teams focused on Web APIs

I want to use natural language

The BDD notation for a scenario is:

Scenario: an example
	GIVEN   some pre-condition
	WHEN    an action is performed
	THEN    an outcome is expected

The text following the keyword (GIVEN | WHEN | THEN) needs to match a phrase/pattern from a vocabulary.

This BDD notation is called "Gherkin". Gherkin is human and machine readable - business analysts, featureers, developers and robots can collaborate.

New features can be created using any simple text editor.

They are invoked elegantly from an API, the command line, Mocha, your IDE or your DevOps workflow.

The results are nicely formatted to help debug, showcase and socialise.

You can download pre-packaged vocabularies and/or roll your own with simple Javascript.

I want to see an example

Dialect features are collections of scenarios.

To improve readability, the keyword AND can be used instead in place of the verbs above.

You can influence what Dialect understands using @nnotations.

Feature: An Example

@example
  Scenario: Trivial Example

  Given I am an example
  When debug works
  And log works
  And error works
  Then I succeed

  Scenario: Trivial Test

    Given I am a trivial test
    When debug ok
    And log ok
    And error ok
    Then I assert this.name == "trivial test"
	And I pass

  @skip
  Scenario: Skip Broken Story

    Given I am broken
    Then I fail

I want to test-drive Dialect

Apigeek Dialect has a limited very Vocabulary of Gherkin - variables, files and templating.

It's probably better to use ApiGeek-Architect instead.

Apigeek Dialect is built using NodeJS.

If you're new to node, pre-read Installing Node.

You install Dialect as a system-wide CLI command:

$ npm install apigeek-dialect -g

To run it simply type:

$ dialect

By default, dialect looks in the "./features" sub-directory. It will create the folder, if it's not found.

However, It won't do much else until we provide some feature scenarios.

First, let's enable Dialect's built-in debugger

export DEBUG=apigeek*

Now, create a file called ./features/example.feature with a simple text editor.

Paste the Feature Example from above.

For more options, type:

$ dialect -h

For example:

If your features are in a different location then use the "--features" or "--epics" option to locate them. These folders are not automatically created, they return an error if not found.

To discover the current vocabulary, type:

$ dialect --knows

I want to embed Dialect into my projects

Create an new Node project:

$ npm init
$ npm install apigeek-dialect -save

Add some domain-specific vocabularies to your package:

$ npm install apigeek-dialect-webapi -save
$ npm install apigeek-dialect-webapp -save
$ npm install apigeek-dialect-blueprint -save

Create a NodeJS main.js script, and copy the following:

#!/usr/bin/env node

var pkg = require("../package");
var _ = require("underscore");
var apigeek = require("apigeek-dialect"), cli = apigeek.cli;
var debug = require("debug")("apigeek:dialect");

cli.version(pkg.version);

apigeek.init();

// auto-install dependent dialects - needed in top-level project to resolve external projects

_.each(pkg.dependencies, function(ver, dep) {
    if (dep.indexOf("dialect-")>=0) {
        debug("install: "+dep+" @ "+ver);
        apigeek.dialect.learn(require(dep),dep);
    }
});

// execute the CLI

apigeek.config.name = apigeek.config.name || pkg.name;
apigeek.execute();

Hopefully, you should be able to extend/embed it from there :-)

For a worked example, take a look at ApiGeek-Architect

I want to license ApiGeek:Dialect

This software is licensed under the Apache 2 license, quoted below.

Copyright 2015-2016 Lee Curtis & Troven 2009-2015

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

[http://www.apache.org/licenses/LICENSE-2.0]

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.