apigeek-dialect

A Dialect for Agile Automation and Governance

Dialect is a Business Driven Development (BDD) tool for architecting, deploying and governing software systems.

You write executable Features (Features and Stories) that can be easily re-used across different projects.

Your features are written in "natural language" so every stakeholder (including the CIO :-) can make sense of them.

See ApiGeek-Architect - a BDD automation tool for "Software Architects"

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 testing the story
    When debug ok
    And log ok
    And error ok
    Then I assert this.name == "story"

  @skip
  Scenario: Skip Broken Story

    Given I am broken
    Then I fail

I want to test-drive Dialect

Apigeek Dialect has a limited Vocabulary.

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

Apigeek Dialect is built using NodeJS.

If you're new to node, pre-read Getting Started.

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 extend Dialect's vocabulary

Dialect ships with only a few simple phrases in it's vocabluary.

Additonal vocabluaries can be easily added.

For using and testing RESTful web APIs

npm install ug-dialect-webapi -g

For using and testing browser-based UIs

npm install apigeek-dialect-webapp -g

For testing network connectivity

npm install apigeek-dialect-net -g

For building software

npm install apigeek-dialect-blueprint -g

Then, in your feature files declare the vocabularies you need:

@dialects=webapi,webapp,net,blueprint

I want to capture my Stories

A scenario describes a Story - essentially it's a list of instructions and expectations.

The framework interprets each step in the scenario using the Gherkin Vocabulary.

Let's expand our initial example, into a hypothetical scenario.

Scenario: Trivial Test

    Given I am testing a story
    When debug feature story works
    And log feature story works
    And error feature story works
    Then I assert this.name == "story"

Dialect reads the GIVEN | WHEN | THEN sentences to build up a feature suite that initializes, executes features and make assertions.

I want to combine Stories into Features

A group of related scenarios is called a "feature" Feature. An Feature is identified by the ".feature" file extension.

For example: the "hello world.feature" file might look like this:

Feature: Verify that variables are working

  Scenario: Test Variable Assignment

    Given I set hello to world
    Then variable hello should match world

I want to re-use feature across multiple projects

Apigeek-Dialect was designed to support a declarative style so that features are portable between dev, feature and production environments.

To achieve portability, environment-specific properties can be declared in a "config" file.

By default, dialect will try to load a configuration file called "apigeek.json" from your current directory.

If no file is found, then sensible default values are defined.

You can change the name of the file using the "--config <file" option.

In this way, your BDD features are neatly abstracted from your runtime configuration.

To specify a custom configuration, use:

dialect --config config.json

If you omit the --config option, then the "apigeek.json" file in the current folder will be used.

Supplying a different "config" file for each environment allows Feature features to be re-used across multiple environments.

I want to perform operations before every scenario

A feature feature may contain a background that are prepended to each scenario. Backgrounds are similar to scenarios, except they do not support annotations.

Background: Authenticate

	GIVEN I login
	AND I use a valid client certificate

I want to add comments

Simple, place a # before any line and it will be ignored by Dialect.

It's useful to add detailed instructions about your intentions or to prevent a statement from running, for example during development.

I want to learn more about Dialect

Gherkin Vocabulary.

Advanced Gherkin.

Something Went Wrong.

I want to license apigeek-dialect

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

Copyright 2016 Lee Curtis [e-mail]

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.