The Postman REST client allows you to write tests for your APIs, such as ensuring that your endpoints return the proper HTTP status codes, headers, and content. It even has has a built-in test runner that makes it easy to run all of your tests and immediately see the results. And you can use the Newman command-line tool to automate your tests and integrate them into your CI and deployment pipeline.
Postman’s built-in test framework uses a boolean-flag syntax for testing, like this:
tests['The correct response code was returned'] = responseCode.code === 200;
tests['The Location header is set'] = postman.getResponseHeader('Location');
tests['The Content-Type is JSON'] = postman.getResponseHeader('Content-Type') === 'application/json';
tests['The response has an ID property'] = JSON.parse(responseBody).id = 12345;
But Postman BDD allows you to use BDD syntax to structure your tests and fluent Chai-JS syntax to write assertions. So the above test suite could look like this instead:
describe('Get customer info', () => {
it('should return a 200 response', () => {
response.should.have.status(200);
});
it('should set the Location header', () => {
response.should.have.header('Location');
});
it('should return a JSON response', () => {
response.should.be.json;
});
it('should return the correct customer', () => {
response.body.should.have.property('id', 12345);
});
});
BDD & fluent syntax
Makes tests easier to write and read
BDD Hooks
Use before
, after
, beforeEach
, and afterEach
hooks to reuse code and tests
Automatic Response Parsing
If the response is JSON or XML, then it is automatically parsed for you. No need to call JSON.parse()
or xml2Json()
first.
Automatic Error Handling
If a script error occurs, only that one test fails. Other tests still run.
Lots of Assertions
Full access to all Chai-JS and Chai-HTTP assertions
Custom Assertions
Define custom Chai-JS assertions for your API to encapsulate logic and make tests more readable
(e.g. response.body.should.be.a.customer
)
Nested describe
blocks
You can nest describe
blocks to logically group your tests
JSON Schema Validation
Use response.body.should.have.schema(someJsonSchema)
to validate responses against a JSON Schema
Detailed logging
You can increase or decrease the amount of information that Postman BDD logs by setting postmanBDD.logLevel
. Errors and warnings are logged by default.
There are two simple steps to installing Postman BDD:
1. Download Postman BDD
Create a GET
request in Postman and point it to the following URL:
http://bigstickcarpet.com/postman-bdd/dist/postman-bdd.min.js
2. Install Postman BDD
In the same request that you created in Step 1, go to the “Tests” tab and add the following script:
// "install" Postman BDD
postman.setGlobalVariable('postmanBDD', responseBody);
Here’s what that should look like:
You now have Postman BDD installed globally. You can use it in any Postman request by “loading” it with the following script:
// Load Postman BDD
eval(globals.postmanBDD);
After you’ve loaded Postman BDD, you can write your tests using BDD syntax and Chai-JS assertions. Here’s an screenshot of a sample collection:
Postman BDD uses Chai.js, Chai-HTTP, and SuperAgent under the hood, so you have access to all three of those libraries to write your tests. Of course, you also have access to the Postman scripting environment, which provides several helpful utility functions and libraries.
The best way to learn how to use Postman-BDD is to check out this sample collection, which includes several examples of both simple and complex API test cases. It also demonstrates some advanced usage, such as re-using code, writing your own custom assertions, etc. Click this button to open the sample collection in Postman:
response
objectThe response
object is what you’ll be doing most of your assertions on. It contains all the information about your HTTP response, such as response.text
, response.body
, response.status
, and even a few shortcut properties like response.ok
and response.error
.
expect
and should
assertionsYou can use any of the Chai-HTTP assertions via Chai’s expect
interface or should
interface. It’s just a matter of personal preference. For example, the following two assertions are identical:
// expect interface
expect(response).to.have.header('content-type', 'application/json');
// should interface
response.should.have.header('content-type', 'application/json');
The normal Postman UI allows you to test individual requests one-by-one and see the results. That’s great for debugging a specific endpoint or scenario, but if you want to run all of your tests, then you’ll want to use Postman’s Collection Runner. To do that, click the “Runner” button in the header bar.
Select the collection you want to run, and any other options that you want — such as an environment, a data file, or the number of iterations to run. Then click the “Start Test” button. You’ll see the test results on the right-hand side, as well as a pass/fail summary at the top. You can also click the “info” icon for any request to see detailed test results for that request.
Postman has a command-line test runner called Newman. If you prefer the CLI instead of a GUI, then this the tool for you. It’s also ideal for continuous-integration and continuous-delivery testing. Just like the Collection Runner, you can run your entire suite of tests, or just a single folder. You can load data from a file, and even write the test results to an output file in various formats (JSON, XML, HTML)
NOTE: Global variables that you create in the Postman app don’t automatically exist in the Newman CLI. This includes the
postmanBDD
variable. You can import global variables into Newman using the--globals
command line argument. Another option is to install Postman BDD as the first request in your collection; that way the collection works anywhere you run it, without relying on the existence of global variables.
I welcome any contributions, enhancements, and bug-fixes. File an issue on GitHub and submit a pull request.
To build/test the project locally on your computer:
Clone this repo
git clone https://github.com/bigstickcarpet/postman-bdd.git
Install dependencies
npm install
Run the tests
npm test
Start the local web server
npm start
(then browse to http://localhost:8080/
Run Postman
Download it here (it’s free)
Run the Postman BDD Collection
Import the Postman BDD Collection, and then use the Postman BDD (localhost) Environment or the Postman BDD (GitHub) Environment to run the collection.
Postman BDD is 100% free and open-source, under the MIT license. Use it however you want.