Apickli is a REST API integration testing framework based on cucumber.js.

It provides a gherkin framework and a collection of utility functions to make API testing easy and less time consuming.

Apickli is also available as an NPM package.

Cucumber.js is JavaScript & Node.js implementation of Behaviour Driven Development test framework - Cucumber. Cucumber.js is using Gherkin language for describing the test scenarios in BDD manner.

Apickli depends on cucumber.js being installed on your system. You can do this by installing cucumber.js globally:

$ npm install -g cucumber

Below steps will help you start a new test project from scratch.

Let's start a new integration testing project for an API called myapi. The folder structure will need to match the structure expected by cucumber.js:

test/
---- features/
--------- myapi.feature
--------- step_definitions/
-------------- myapi.js
---- package.json

Features directory contains cucumber feature files written in gherkin syntax. step_definitions contains the JavaScript implementation of gherkin test cases. Check out the GitHub repository for example implementations covering most used testing scenarios.

This can be an example package.json file for our project:

{
	"name": "myapi-test",
	"version": "1.0.0",
	"description": "Integration testing for myapi v1",
	"dependencies": {
		"apickli": "latest"
	}
}

Now we can get the project dependencies installed:

$ npm install

Let's start with the scenario file called myapi.feature. For more examples of feature and scenario definitions, check out test folder.

Feature:
	Httpbin.org exposes various resources for HTTP request testing
	As Httpbin client I want to verify that all API resources are working as they should

	Scenario: Setting headers in GET request
		Given I set User-Agent header to apickli
		When I GET /get
		Then response body path $.headers.User-Agent should be apickli

We now need the corresponding step definitions that implement the steps in our scenario. Apickli has a collection of steps already implemented - ready to be included in your project: source/apickli/apickli-gherkin.js. It is included in the NPM package so you can symlink to it from under your local node_modules/apickli folder - see gherkin expressions for more information and help on symlink.

Now we need a step definition file specific for this project, let's call it myapi.js:

/* jslint node: true */
'use strict';

var apickli = require('apickli');

module.exports = function() {
	// cleanup before every scenario
	this.Before(function(scenario, callback) {
		this.apickli = new apickli.Apickli('http', 'httpbin.org');
		callback();
	});
};

The following will run our scenario (in the project directory):

$ cucumber-js features/httpbin.feature
....

1 scenario (1 passed)
3 steps (3 passed)

Cucumber.js default step timeout is 5000ms. Follow this guide to change it for your steps.

You can also use Grunt task runner to run the tests.

'use strict';

module.exports = function(grunt) {
	grunt.initConfig({
		cucumberjs: {
			src: 'features',
			options: {
				format: 'pretty',
				steps: 'features/step_definitions'
			}
		}
	});

	grunt.loadNpmTasks('grunt-cucumber');
	grunt.registerTask('tests', ['cucumberjs']);
}

	...
	"dependencies": {
		"apickli": "latest",
		"grunt": "latest",
		"grunt-cucumber": "latest"
	}
	...

npm install

$ grunt tests
Running "cucumberjs:src" (cucumberjs) task

Feature:
  Httpbin.org exposes various resources for HTTP request testing
  As Httpbin client I want to verify that all API resources are working as they should


  Scenario: Setting headers in GET request                         # features/httpbin.feature:5
    Given I set User-Agent header to apickli                       # features/httpbin.feature:6
    When I GET /get                                                # features/httpbin.feature:7
    Then response body path $.headers.User-Agent should be apickli # features/httpbin.feature:8


1 scenario (1 passed)
3 steps (3 passed)

Done, without errors.

You can also use Gulp to run the tests.

var gulp = require('gulp');
var cucumber = require('gulp-cucumber');

gulp.task('test', function() {
    return gulp.src('features/*')
			.pipe(cucumber({
				'steps': 'features/step_definitions/*.js',
				'format': 'pretty'
			}));
});

...
	"gulp": "latest",
	"gulp-cucumber": "latest"
...

$ npm install

$ npm install -g gulp

See https://github.com/gulpjs/gulp/blob/master/docs/getting-started.md.

$ gulp test

The following gherkin expressions are implemented in apickli source code source/apickli/apickli-gherkin.js:

GIVEN:
	I set (.*) header to (.*)
    I set cookie to (.*)
	I set body to (.*)
	I pipe contents of file (.*) to body
	I have basic authentication credentials (.*) and (.*)
	I set bearer token
	I set query parameters to (data table with headers |parameter|value|)
	I set headers to (data table with headers |name|value|)

WHEN:
	I GET $resource
	I POST to $resource
	I PUT $resource
	I DELETE $resource
	I PATCH $resource
    	I request OPTIONS for $resource

THEN:
	response code should be (\d+)
	response code should not be (\d+)
	response header (.*) should exist
	response header (.*) should not exist
	response header (.*) should be (.*)
	response header (.*) should not be (.*)
	response body should be valid (xml|json)
	response body should contain (.*)
	response body should not contain (.*)
	response body path (.*) should be (.*)
	response body path (.*) should not be (.*)
    	response body path (.*) should be of type array
    	response body path (.*) should be of type array with length (\d+)
    	response body should be valid according to schema file (.*)
    	response body should be valid according to swagger definition (.*) in file (.*)
	I store the value of body path (.*) as access token
	I store the value of response header (.*) as (.*) in scenario scope
	I store the value of body path (.*) as (.*) in scenario scope
	value of scenario variable (.*) should be (.*)
	I store the value of response header (.*) as (.*) in global scope
	I store the value of body path (.*) as (.*) in global scope

The simplest way to adopt these expressions is to create a file named apickli-gherkin.js in features/step_definitions and extend the apickli/gherkin.js module.

add the following to test/features/step_definitions/apickli-gherkin.js

module.exports = require('apickli/apickli-gherkin');

If using Windows, follow this guide to create a symlink: How-To Geek Guide.

apickli uses node.js request module for HTTP communications which supports setting proxy servers via the following environment variables:

• HTTP_PROXY / http_proxy
• HTTPS_PROXY / https_proxy
• NO_PROXY / no_proxy

For more information, see https://github.com/request/request#controlling-proxy-behaviour-using-environment-variables

It is possible to use Scenario Variables in a Feature file, that will have values injected when the tests are run. Whilst defining values explicitly provides better clarity to those reading a feature file, there are some configuration values such as Client Id which it is easier to externalise.

By default, backticks are use to indicate a variable in a feature file. When instantiating Apickli, a different character can be passed as a parameter. In order to follow BDD best practices, global variables should not be used in the way. Each Scenario should be independent, and as such if you would like to define configurable variables it should be done using the Before hook:

/* jslint node: true */
'use strict';

var apickli = require('apickli');

module.exports = function() {
	// cleanup before every scenario
	this.Before(function(scenario, callback) {
		this.apickli = new apickli.Apickli('http', 'httpbin.org');
        this.apickli.storeValueInScenarioScope("BasicAuthValue", "Basic abc123");
		callback();
	});
};

Feature:
  Httpbin.org exposes various resources for HTTP request testing
  As Httpbin client I want to verify that all API resources are working as they should


  Scenario: Setting authorization headers in GET request                         
    Given I set Authorization header to `BasicAuthValue`                       
    When I GET /get                                                
    Then response body path $.headers.Authorization should be Basic abc123

For more examples, please see source/test/features/injecting-variables.feature

If you have any comments or suggestions, feel free to raise an issue or fork the project and issue a pull request with suggested improvements.