<commit_before># apickli - API integration testing framework

**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](https://www.npmjs.com/package/apickli).

[Cucumber.js](https://github.com/cucumber/cucumber-js) is JavaScript & Node.js implementation of Behaviour Driven Development test framework - [Cucumber](http://cukes.info/). Cucumber.js is using [Gherkin](http://cukes.info/gherkin.html) language for describing the test scenarios in [BDD](http://en.wikipedia.org/wiki/Behavior-driven_development) manner.  

## How to start - a simple tutorial

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

    $: npm install -g cucumber

### Copy example project

You can copy existing [example-project](example-project) directory in this code repository which has skeleton test project created with tests against `httpbin.org`

### Start new project

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

### 1. Folder structure
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.

### 2. Package.json
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"
	}
}
```

### 3. Install dependencies
Now we can get the project dependencies installed: 

    $ npm install
    
### 4. Scenario definitions
We can now start defining our scenarios for the test. For this tutorial, we will be borrowing sections from the [example project](example-project/) in apickli source code. 

Let's start with the scenario file called *myapi.feature*. Full scenario definition with various other functions can be found here: [example-project/features/httpbin.feature](example-project/features/httpbin.feature)

```
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
```

### 5. Get apickli-gherkin steps
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](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 [example-project/features/step_definitions/apickli-gherkin.js](example-project/features/step_definitions/apickli-gherkin.js) for symlink. 

Refer to [Gherkin Expressions](#gherkin-expressions) section below to see a list of steps implemented by apickli-gherkin.

### 6. Step_definitions for this project
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(callback) {
		this.apickli = new apickli.Apickli('http', 'httpbin.org');
		callback();
	});
};
```

### 7. Run tests with cucumber.js
The following will run our scenario (in the project directory):

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

	1 scenario (1 passed)
	3 steps (3 passed)
	
## Grunt integration
    
You can also use [Grunt](http://gruntjs.com/) task runner to run the tests. 

### 1. Start by adding a Gruntfile.js to the project root:

```
'use strict';

module.exports = function(grunt) {
	grunt.initConfig({
		cucumberjs: {
			src: 'features',
			options: {
				format: 'pretty',
				steps: 'features/step_definitions'<commit_msg>README file subsection headings<commit_after># apickli - API integration testing framework

**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](https://www.npmjs.com/package/apickli).

[Cucumber.js](https://github.com/cucumber/cucumber-js) is JavaScript & Node.js implementation of Behaviour Driven Development test framework - [Cucumber](http://cukes.info/). Cucumber.js is using [Gherkin](http://cukes.info/gherkin.html) language for describing the test scenarios in [BDD](http://en.wikipedia.org/wiki/Behavior-driven_development) manner.  

## How to start - a simple tutorial

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

    $: npm install -g cucumber

### Copy example project

You can copy existing [example-project](example-project) directory in this code repository which has skeleton test project created with tests against `httpbin.org`

### Start new project

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

#### 1. Folder structure
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.

#### 2. Package.json
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"
	}
}
```

#### 3. Install dependencies
Now we can get the project dependencies installed: 

    $ npm install
    
#### 4. Scenario definitions
We can now start defining our scenarios for the test. For this tutorial, we will be borrowing sections from the [example project](example-project/) in apickli source code. 

Let's start with the scenario file called *myapi.feature*. Full scenario definition with various other functions can be found here: [example-project/features/httpbin.feature](example-project/features/httpbin.feature)

```
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
```

#### 5. Get apickli-gherkin steps
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](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 [example-project/features/step_definitions/apickli-gherkin.js](example-project/features/step_definitions/apickli-gherkin.js) for symlink. 

Refer to [Gherkin Expressions](#gherkin-expressions) section below to see a list of steps implemented by apickli-gherkin.

#### 6. Step_definitions for this project
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(callback) {
		this.apickli = new apickli.Apickli('http', 'httpbin.org');
		callback();
	});
};
```

#### 7. Run tests with cucumber.js
The following will run our scenario (in the project directory):

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

	1 scenario (1 passed)
	3 steps (3 passed)
	
## Grunt integration
    
You can also use [Grunt](http://gruntjs.com/) task runner to run the tests. 

### 1. Start by adding a Gruntfile.js to the project root:

```
'use strict';

module.exports = function(grunt) {
	grunt.initConfig({
		cucumberjs: {
			src: 'features',
			options: {
				format: 'pretty',
				steps: 'features/step_definitions'
{'fraction_non_alphanumeric': 0.09943086709072649, 'fraction_numerical': 0.003571030018971097, 'mean_word_length': 4.040494938132733, 'pattern_counts': {'":': 10, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 4, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6972846', 'n_tokens_mistral': 2625, 'n_tokens_neox': 2475, 'n_words': 1022}