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
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);
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;
});
});
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 nestdescribe
blocks to logically group your tests -
Hooks - Postman BDD supports all the standard BDD hooks:
before
,after
,beforeEach
, andafterEach
, 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.
The Postman BDD API is identical to Chai HTTP's API, which is in-turn based on SuperAgent's API.
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
.
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")
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)
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
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/
Postman BDD is 100% free and open-source, under the MIT license. Use it however you want. I