enterstudio / postman-bdd

A BDD test framework for Postman and Newman

Postman BDD

BDD test framework for Postman and Newman

This project is a port of Chai HTTP that runs in the Postman REST Client. The API is exactly the same, but instead of using chai.request("http://my-server.com"), you can use the Postman GUI to build and send your HTTP request.

• Usage
• Advanced Usage
• API Documentation
• Running tests in bulk
• Running tests from the command line
• Debugging tests

Example

Installation

To install Postman BDD in Postman, just create a GET request to postman-bdd.js or postman-bdd.min.js. (The latter is a smaller download, the former is easier to debug)

Go to the "Tests" tab of this request, and add the following script:

// "install" Postman BDD
postman.setGlobalVariable('postmanBDD', responseBody);

Usage

You now have Postman BDD installed globally. You can use it in any Postman request like this:

// Load Postman BDD
eval(postman.getGlobalVariable('postmanBDD'));

describe('Get user info', function() {
    it('should return user data', function() {
       response.should.have.status(200);
       response.should.be.json;
       response.body.should.not.be.empty;
    });

    it('should have a full name', function() {
      var user = response.body.results[0].user;
      user.name.should.be.an('object');
      user.name.should.have.property('first').and.not.empty;
      user.name.should.have.property('last').and.not.empty;
      user.name.should.have.property('that-does-not-exist');
    });

    it('should have an address', function() {
      var user = response.body.results[0].user;
      user.location.should.be.an('object');
      user.location.should.have.property('street').and.not.empty;
      user.location.should.have.property('city').and.not.empty;
    });
});

Advanced Usage

Postman BDD supports more advanced features too. I'll add documentation for them soon, but here's a little teaser :)

• Simple debugging - When a debugger is attached, Postman BDD will automatically pause when a test fails so you can debug it.

• Nested describe blocks - In standard BDD pattern, you can nest describe blocks to logically group your tests

• Hooks - Postman BDD supports all the standard BDD hooks: before, after, beforeEach, and afterEach, so you can reuse tests across multiple requests in your REST API.

• JSON Schema Validation - Postman BDD includes an assertion response.body.should.have.schema(someJsonSchema), which allows you to validate your API's responses against a JSON Schema. This is especially great if you've already built a Swagger schema for your API.

API Documentation

The Postman BDD API is identical to Chai HTTP's API, which is in-turn based on SuperAgent's API.

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 (for JSON responses), 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');

Other assertsions you can do include response.should.be.html, response.should.have.status(200), and response.should.redirectTo("http://example.com")

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)

Debugging tests

Postman is actually an HTML-based application, running in an embedded Chrome browser instance. So you canuse Chrome's built-in developer tools to debug. On Windows, press F12 to open the developer tools. On Mac, press cmd+alt+i.

Note: You may need to enable debugging for packed apps first

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/

License

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