# API Testing Tips from a Postman Professional

As an engineer at Postman, I talk to a lot of people who use Postman to test their APIs. Over the years, I’ve picked up 10 tips and tricks for simplifying and automating the task of API testing. **Related: [Use the API Templates for Testing](https://www.postman.com/templates/collections/tags/testing/)**

### TIP #1: write tests

 The first step to [API testing](https://www.postman.com/api-platform/api-testing/) is to actually do it. Without good tests, it’s impossible to have full confidence in your API’s behavior, consistency, or backward compatibility. As your codebase grows and changes over time, tests will save you time and frustration by spotting breaking changes. [Writing tests in Postman is easy](https://learning.postman.com/docs/postman/scripts/test-scripts/) and uses JavaScript syntax. Testing simple things, like HTTP status codes, response times, and headers can each be done in a single line of code, like this: https://gist.github.com/JamesMessinger/84963608c522637bc46309e1c24d82f8 But you can also write more advanced JavaScript logic to validate responses, check custom business rules, [persist data to variables](https://learning.postman.com/docs/postman/scripts/test-examples/), or even [dynamically control Postman's workflow](https://learning.postman.com/docs/postman/scripts/branching-and-looping/). ### TIP #2: don't mix tests and documentation

 Many people use [Postman Collections](https://learning.postman.com/docs/postman/collections/creating-collections/) to document their APIs, either as a collection of example requests that can be easily [shared among team members](https://learning.postman.com/docs/collaborating-in-postman/sharing/), or as [public API documentation](https://learning.postman.com/docs/postman-for-publishers/public-api-docs/) for customers. For both of those use cases, it makes sense for your collection to contain detailed explanations for each of your [API endpoints](https://blog.postman.com/what-is-an-api-endpoint/), walkthroughs of common API workflows, authentication requirements, lists of possible error responses, etc. Your API tests, on the other hand, serve an entirely separate purpose. First of all, the audience is different. Whereas [API documentation](https://www.postman.com/api-platform/api-documentation/) is for the *consumers* of an API, tests are for the *authors* of an API. Secondly, the content is different. A solid test suite will include many edge cases, intentional bad inputs (to test error handling), and possibly reveal sensitive information, all of which would be irrelevant or confusing for your API's consumers. And finally, the authors are possibly different. Documentation (especially public docs) may be written by your marketing team or technical writers, whereas tests are written by the developers who built the API or the testers who are responsible for validating the API. For all of these reasons, I highly recommend that you keep your API tests in a **separate collection** from your API documentation. Yes, that means that you have to manage two different collections, but in my experience, the contents of these collections end up being so vastly different that there's almost no overlap or duplication between them. And, as you'll see later in this article, having your tests separated in their own collection opens up some powerful automation possibilities. **> Bonus Tip:** The description fields that you'd normally use for your API documentation can be repurposed as test descriptions. It's a great way to document your tests, so developers and testers know what's being tested, what the expected output is, etc. [![A request with a test description](https://blog.postman.com/wp-content/uploads/2017/07/test-with-description.png)](https://blog.postman.com/wp-content/uploads/2017/07/test-with-description.png)### TIP #3: organize tests into folders

 As your API grows in complexity, it will become important to organize your tests so they make sense and can be found easily. I suggest that you [use folders to group requests](https://learning.postman.com/docs/postman/collections/managing-collections/#adding-folders) by resource, test suite, and workflows. ##### Resources

 Create a top-level folder for each of your API's [resources](https://restful-api-design.readthedocs.io/en/latest/resources.html) (users, orders, products, etc.). ##### Test Suites

 The second-level folders would be test suites for each of those resources, such as "*Start a new order*", "*Edit an existing order*", "*Cancel an order*", etc. For simple tests that only require a single API call, there's no need for a third level of folders. You can simply create requests directly under the test suite folder. Be sure to give your requests meaningful names to differentiate them and describe what they're testing. For example, the "*Edit an existing order*" test suite folder might contain requests such as "*Add a product*", "*Remove a product*", "*Change the shipping address*", etc. ##### Workflows

 The third-level folders are for more complicated tests that span multiple API calls. For example, your API might have a checkout flow that involves separate calls to create an order from a shopping cart, enter the shipping address, select the shipment method, and submit the payment information. In this case, you'd create a "workflow" folder named something like "*Checkout*" that contains the three requests. [![Nested test folders](https://blog.postman.com/wp-content/uploads/2017/07/nested-folders.png)](https://blog.postman.com/wp-content/uploads/2017/07/nested-folders.png)### TIP #4: JSON Schema validation

 Many modern APIs use some form of [JSON Schema](https://spacetelescope.github.io/understanding-json-schema/about.html) to define the structure of their requests and responses. Postman includes the [tv4](https://geraintluff.github.io/tv4/) library, which makes it easy to write tests to verify that your API responses comply with your JSON Schema definitions. https://gist.github.com/JamesMessinger/46bb549a7ffadf1aaab0c3f353b0064d Of course, you probably wouldn't want to hard code your JSON Schema in your test script, especially since you may need to use the same schema for many requests in your collection. So, instead, you could store the schema as a JSON string in a [Postman environment variable](https://learning.postman.com/docs/sending-requests/variables/). Then you can simply use the variable in your test script, like this: https://gist.github.com/JamesMessinger/fba37542221b2128603a480aa1100ad2 ### TIP #5: reuse code

 In the previous tip, I showed you how to easily reuse the same JSON Schema for multiple requests in your collection by storing it in an environment variable. You can also reuse JavaScript code the same way by leveraging the [`eval()` function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/eval). Most APIs have some common rules that apply to most (or all) endpoints. Certain [HTTP headers](https://blog.postman.com/what-are-http-headers/) should always be set, or the response body should always be in a certain format, or the response time must always be within an acceptable limit. Rather than re-writing these tests for every request, you can write them once in the very first request of your collection and reuse them in every request after that. ##### First request in the collection:

 https://gist.github.com/JamesMessinger/bef06d26de2145bbf0a5de2addd77eaf ##### Other requests in the collection:

 https://gist.github.com/JamesMessinger/82efb4b41075f1eb5df392bd879b017d There's no limit to the amount of code that can be stored in a variable and reused this way. In fact, you can use this trick to reuse entire JavaScript libraries, including many third-party libraries from [NPM](https://www.npmjs.com/), [Bower](https://bower.io/), and [GitHub](https://github.com/trending/javascript). ### TIP #6: Postman BDD

 Postman's default test syntax is really straightforward and easy to learn, but many people prefer the syntax of popular JavaScript test libraries such as [Mocha](https://mochajs.org/) and [Chai](http://chaijs.com/). I happen to be one of those people, which is why I created [Postman BDD](https://github.com/JamesMessinger/postman-bdd). Postman BDD allows you to write Postman tests using [Mocha's BDD syntax](https://mochajs.org/#bdd). It leverages the "reusable code" trick from the previous tip to load [Chai](http://chaijs.com/) and [Chai-HTTP](http://chaijs.com/plugins/chai-http/), which means you can write tests like this: https://gist.github.com/JamesMessinger/ad0746045e29497e1b1e22f8fa9ae39b In addition to the fluent syntax, Postman BDD has several other [features and benefits](https://github.com/BigstickCarpet/postman-bdd/#features--benefits) that make Postman tests even easier and more powerful. Follow the [installation instructions](https://github.com/BigstickCarpet/postman-bdd/#installation) or check out the [sample collection](https://app.getpostman.com/run-collection/3aa9116ba36136628303) to get started. ### TIP #7: automate your tests with Postman's collection runner

 Up to now, we've focused on running a single request and testing the response. That approach works great while you're writing your tests, but once they're all written, you'll want an easy way to run *all* of your requests quickly and see the results in a single view. That's where [Postman's collection runner](https://learning.postman.com/docs/postman/collection-runs/starting-a-collection-run/) comes in. [![The Postman Runner](https://blog.postman.com/wp-content/uploads/2017/07/runner.png)](https://blog.postman.com/wp-content/uploads/2017/07/runner.png)### TIP #8: automate your tests with Newman

 The Postman collection runner is a great way to run all of your tests and see the results, but it still requires you to manually initiate the run. If you want to run your Postman tests as part of your Continuous Integration or Continuous Delivery pipeline, then you'll need to use the [Newman CLI](https://github.com/postmanlabs/newman). Newman can easily be integrated into [Jenkins](https://learning.postman.com/docs/postman/collection-runs/integration-with-jenkins/), [AppVeyor](https://www.appveyor.com/), [Bamboo](https://www.atlassian.com/software/bamboo), [CodeShip](https://codeship.com/), [Travis CI](https://travis-ci.org/), [Circle CI](https://circleci.com/), or any other code deployment pipeline tool. It supports a variety of [output formats](https://github.com/postmanlabs/newman#configuring-reporters), including a human-friendly console output, as well as outputting to a JSON or HTML file. [![Newman CLI](https://blog.postman.com/wp-content/uploads/2017/07/newman.gif)](https://blog.postman.com/wp-content/uploads/2017/07/newman.gif)### TIP #9: automate your tests with Postman Monitors

 You can use [Postman Monitors](https://learning.postman.com/docs/postman/monitors/intro-monitors/) to automatically run your Postman tests at regular intervals, such as every night, or every 5 minutes. You'll automatically be notified if any of your tests ever fail, and you can even [integrate](https://learning.postman.com/docs/integrations/intro-integrations/) with a variety of third-party services, such as [PagerDuty](https://www.pagerduty.com/), [Slack](https://slack.com/), [Datadog](https://www.datadoghq.com/), and [more](https://go.postman.co/workspaces). Postman Monitors shows your test results in the same familiar layout as the Postman collection runner, so it's easy to compare the results to the Postman app. [![Postman Monitors](https://blog.postman.com/wp-content/uploads/2017/07/monitors.png)](https://blog.postman.com/wp-content/uploads/2017/07/monitors.png)### TIP #10: dynamically control test workflows

 By default, the Postman collection runner, Newman, and Postman Monitors will run each request in your collection in order. But you can use the [`postman.setNextRequest()`](https://learning.postman.com/docs/postman/scripts/branching-and-looping/) function to change the order. This allows you to conditionally skip certain requests, repeat requests, terminate the collection early, etc. https://gist.github.com/JamesMessinger/1e6702e0c96be032d905adb274727baa The `setNextRequest()` function is deceptively simple, but it enables all sorts of powerful use cases, from [generating a Spotify playlist](https://blog.postman.com/generate-spotify-playlists-using-a-postman-collection/), to [checking your website for broken links](https://blog.postman.com/check-for-broken-links-on-your-website-using-a-postman-collection/), or even [deciding what to feed your dog](https://blog.postman.com/conditional-workflows-in-postman/).