apigeek-dialect

A Dialect for Agile Automation and Governance

Use naturual language to write executable Epics and easily re-use them across different projects.

Since Epics are written in "executable natural language" - every stakeholder can make sense of them.

Including the CIO :-)

I want to automate myself

In a nutshell, Apigeek-Dialect is an automation tool to describe executable process and governance.

Behaviour Driven Development (BDD) is an emerging best practice for architecting software.

When using Dialect, an Epic is known as a "Feature" and a Story is called a "Scenario".

A Feature collects together related Scenarios.

Each Scenario describes the expected behavior and outcomes in a way that is both human and machine friendly.

Each scenario is described using the Gherkin syntax: GIVEN -> WHEN -> THEN

I want to see an example

Dialect will execute every scenario that is grouped together into a set of "features".

Feature: An Example

@example
  Scenario: Trivial Example

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

  Scenario: Trivial Test

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

  @skip
  Scenario: Skip Broken Story

    Given I am broken
    Then I fail

I want to involve diverse stakeholders

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.

I want to use natural language

The general BDD pattern to describe a scenario is:

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

This notation is commonly called "Gherkin". To improve readability, the keyword AND can be used instead in place of the verbs above.

The text following the keyword (GIVEN | WHEN | THEN) needs to match a pattern that is understood by Apigeek-Dialect.

The supported patterns can be found in the Dialect Vocabulary

I want to feature-drive Dialect

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

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

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

export DEBUG=dialect*

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 featureing the 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 Epics

A group of related scenarios is called a "feature" Epic. An Epic 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 feature to hello
    Then variable feature should match hello

By default, dialect looks in the "./features" sub-directory.

If your features are in a different location, you can use the "--features" or "--feature" option to locate them.

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 be notified when Stories and Epics are run and pass or fail

Dialect can send you a web hook notifications via Slack.

To confirm it simply add a section to your JSON config file:

{ 
	"webhooks": {
		"slack": {
			"username": "dialect-bot",
			"channel": "#featureing",
			"url": "https://hooks.slack.com/services/XXXXXXXXX/YYYYYYYY/ZZZZZZZZ"
		}
	}
}

Once you have an active Slack account then obtain a new Slack webhook URL

You will receive events when scenarios start, finish successfully or fail.

I have multiple / complex runtime environments

Most teams have multiple target environments such as "dev", "feature" and "prod".

The config file supports a "target" definition that supports named environments.

An example that supports multiple targets, user agents and certificates:

{
	"protocol": "http",
	"hostname": "google.com",
	"port": "80",

	"target": {
		"google": {
			"protocol": "http",
			"hostname": "google.com",
			"port": "80"
		},
		"secure-google": {
			"protocol": "https",
			"hostname": "google.com",
			"port": "443"
		}
	},
}

You can switch to different targets using the command line options "--target "

{
	"protocol": "http",
	"hostname": "google.com",
	"port": "80",

	"target": {
		"secure": {
			"protocol": "https",
			"hostname": "example.com",
			"port": "443",
			"agent": {
				"default": {
					"username": "[e-mail]",
					"password": "TEST1234"
				}
			},
		
			"certificate": {
				"valid": {
					"key": "../etc/certs2/client/app-client.key.pem",
					"cert": "../etc/certs2/client/app-client.crt.pem",
					"ca": "../etc/certs2/ca/root-ca.crt.pem",
					"passphrase": "feature"
				}
			}
		},
	},

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.