Product
Introducing SSO
Streamline your login process and enhance security by enabling Single Sign-On (SSO) on the Socket platform, now available for all customers on the Enterprise plan, supporting 20+ identity providers.
bitter-apple
Advanced tools
Readme
BitterApple 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.
BitterApple 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.
BitterApple started as a fork of Apickli.
It adds the following features to Apickli:
BitterApple depends on cucumber.js being installed on your system. You can do this by installing cucumber.js globally:
$ npm install -g cucumber
You can copy existing example-project directory in this code repository which has skeleton test project created with tests against httpbin.org
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": {
"bitterapple": "latest"
}
}
Now we can get the project dependencies installed:
$ npm install
We can now start defining our scenarios for the test. For this tutorial, we will be borrowing sections from the example project in bitterapple 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
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 bitterapple
When I GET /get
Then response body path $.headers.User-Agent should be bitterapple
We now need the corresponding step definitions that implement the steps in our scenario. BitterApple has a collection of steps already implemented - ready to be included in your project: source/bitterapple/bitterapple-gherkin.js. It is included in the NPM package so you can symlink to it from under your local node_modules/bitterapple folder - see example-project/features/step_definitions/bitterapple-gherkin.js for symlink.
Refer to Gherkin Expressions section below to see a list of steps implemented by bitterapple-gherkin.
Now we need a step definition file specific for this project, let's call it myapi.js:
/* jslint node: true */
'use strict';
var bitterapple = require('bitterapple');
module.exports = function() {
// cleanup before every scenario
this.Before(function(scenario, callback) {
this.bitterapple = new bitterapple.BitterApple('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": {
"bitterapple": "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 bitterapple # features/httpbin.feature:6
When I GET /get # features/httpbin.feature:7
Then response body path $.headers.User-Agent should be bitterapple # 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 bitterapple source code source/bitterapple/bitterapple-gherkin.js:
GIVEN:
I set (.*) header to (.*)
I set body to (.*)
I pipe contents of file (.*) to body
I have basic authentication credentials (.*) and (.*)
I set bearer token
I set (.*) header to scenario variable (.*)
I set (.*) header to global variable (.*)
I send the cookie (.*)
I clear the cookie (.*)
WHEN:
I GET $resource
I POST to $resource
I PUT $resource
I PATCH $resource
I DELETE $resource
I POST to $resource with body
"""
(.*)
"""
I PUT $resource with body
"""
(.*)
"""
I PATCH $resource with body
"""
(.*)
"""
I DELETE $resource with body
"""
(.*)
"""
THEN:
response header (.*) should exist
response header (.*) should not exist
response body should be valid (xml|json)
response code should be (\d+)
response code should not be (\d+)
response header (.*) should be (.*)
response header (.*) should not be (.*)
response body should contain (.*)
response body should not contain (.*)
response body at path (.*) should be a json array
response body at path (.*) should be an array of length (\d+)
response body path (.*) should be (.*)
response body path (.*) should not be (.*)
I store the value of body path (.*) as access token
I store the value of header (.*) 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 (.*)
value of global 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 JSON should be
"""
(.*)
"""
The simplest way to adopt these expressions is to create a symlink from node_modules/bitterapple/bitterapple-gherkin.js to features/step_definitions/bitterapple-gherkin.js
$ ln -s node_modules/bitterapple/bitterapple-gherkin.js features/step_definitions/bitterapple-gherkin.js
If using Windows, follow this guide to create a symlink: How-To Geek Guide.
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.
FAQs
Collection of utility functions and a gherkin framework for WEB API integration testing based on cucumber.js
The npm package bitter-apple receives a total of 11 weekly downloads. As such, bitter-apple popularity was classified as not popular.
We found that bitter-apple demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Product
Streamline your login process and enhance security by enabling Single Sign-On (SSO) on the Socket platform, now available for all customers on the Enterprise plan, supporting 20+ identity providers.
Security News
Tea.xyz, a crypto project aimed at rewarding open source contributions, is once again facing backlash due to an influx of spam packages flooding public package registries.
Security News
As cyber threats become more autonomous, AI-powered defenses are crucial for businesses to stay ahead of attackers who can exploit software vulnerabilities at scale.