No commit activity in last 3 years
No release in over 3 years
There's a lot of open issues
cucumber-api allows API JSON response validation and verification in BDD style.
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
 Dependencies

Runtime

 Project Readme

cucumber-api

Build Status Gem Version Dependency Status Code Climate Total Downloads

API validator in BDD style with Cucumber. cucumber-api lets one validate public APIs JSON response in blazingly fast time.

Inspired by cucumber-api-steps.

Checkout sample to see cucumber-api in action.

Installation

Add cucumber-api gem to your Gemfile:

gem 'cucumber-api'

Require cucumber-api in your Cucumber's env.rb:

require 'cucumber-api'

Configuration

Verbose logging: enable verbose logging of API calls and responses by setting cucumber_api_verbose=true in your ENV, preferably via your cucumber.yml

# config/cucumber.yml
##YAML Template
---
verbose     : cucumber_api_verbose=true

Usage

Available steps

Preparation steps

Specify your request header's Content-Type and Accept. The only supported option for Accept is application/json at the moment.

Given I send and accept JSON
Given I send "(.*?)" and accept JSON

You could also others header's information like:

Given I send and accept JSON
And I add Headers:
  | name1 | value |
  | name2 | other |  

Specify POST body

When I set JSON request body to '(.*?)'
When I set form request body to:
  | key1 | value1              |
  | key2 | {value2}            |
  | key3 | file://path-to-file |
When I set JSON request body to:
"""
{
  "key1": "jsonString",
  "key2":  1
}
"""

Or from YAML/JSON file

When I set request body from "(.*?).(yml|json)"

Example:

Given I send "www-x-form-urlencoded" and accept JSON
When I set JSON request body to '{"login": "email@example.com", "password": "password"}'
When I set form request body to:
  | login    | email@example.com     |
  | password | password              |
When I set request body from "data/json-data.json"
When I set request body from "data/form-data.yml"

Request steps

Specify query string parameters and send an HTTP request to given URL with parameters

When I send a (GET|POST|PATCH|PUT|DELETE) request to "(.*?)"
When I send a (GET|POST|PATCH|PUT|DELETE) request to "(.*?)" with:
  | param1 | param2 | ... |
  | value1 | value2 | ... |

Temporarily save values from the last request to use in subsequent steps in the same scenario:

When I grab "(.*?)" as "(.*?)"

Optionally, auto infer placeholder from grabbed JSON path:

# Grab and auto assign {id} as placeholder
When I grab "$..id"

The saved value can then be used to replace {placeholder} in the subsequent steps.

Example:

When I send a POST request to "http://example.com/token"
And I grab "$..request_token" as "token"
And I grab "$..access_type" as "type"
And I grab "$..id"
And I send a GET request to "http://example.com/{token}" with:
  | type            | pretty |
  | {type}          | true   |
Then the JSON response should have required key "id" of type string and value "{id}"

Assume that http://example.com/token have an element {"request_token": 1, "access_type": "full", "id": "user1"}, cucumber-api will execute the followings:

This will be handy when one needs to make a sequence of calls to authenticate/authorize API access.

Assert steps

Verify:

  • HTTP response status code
  • JSON response against a JSON schema conforming to JSON Schema Draft 4
  • Adhoc JSON response key-value type pair, where key is a JSON path
Then the response status should be "(\d+)"
Then the JSON response should follow "(.*?)"
Then the JSON response root should be (object|array)
Then the JSON response should have key "([^\"]*)"
Then the JSON response should have (required|optional) key "(.*?)" of type (numeric|string|boolean|numeric_string|object|array|any)( or null)
Then the JSON response should have (required|optional) key "(.*?)" of type (numeric|string|boolean|numeric_string|object|array|any)( or null) and value "(.*?)"

Example:

Then the response status should be "200"
Then the JSON response should follow "features/schemas/example_all.json"
Then the JSON response root should be array
Then the JSON response should have key "id"
Then the JSON response should have optional key "format" of type string or null
Then the JSON response should have required key "status" of type string and value "foobar"

Also checkout sample for real examples. Run sample with the following command:

cucumber -p verbose

Response caching

Response caching is provided for GET requests by default. This is useful when you have a Scenario Outline or multiple Scenarios that make GET requests to the same endpoint.

Only the first request to that endpoint is made, subsequent requests will use cached response. Response caching is only available for GET method.

The response cache can also be cleared if needed:

Given I clear the response cache

Dependencies