OLD_README.md

Overview

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);
  });

});

Features & Benefits

• 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.

Installation

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:

Usage

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:

Writing Tests

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 object

The 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 assertions

You 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');

Running tests in bulk

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.

Running tests from the command line

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 --globalscommand 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.

Contributing

I welcome any contributions, enhancements, and bug-fixes. File an issue on GitHub and submit a pull request.

Building/Testing

To build/test the project locally on your computer:

1. Clone this repo
   git clone https://github.com/bigstickcarpet/postman-bdd.git

2. Install dependencies
   npm install

3. Run the tests
   npm test

4. Start the local web server
   npm start (then browse to http://localhost:8080/

5. Run Postman
   Download it here (it's free)

6. 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.

License

Postman BDD is 100% free and open-source, under the MIT license. Use it however you want.