Simulate user traffic to test your API performance
Test the performance of your APIs with Postman. Simulate user traffic by automatically sending requests from your local machine, your CI/CD environment, or Postman Cloud, using the Postman app or the Postman CLI. You can observe how your API behaves under load and identify potential issues or bottlenecks that affect performance.
Test API performance with virtual users
To configure a performance test, create a collection with the requests you want to send to your API. Postman uses these requests to simulate the activity of your API’s users. Each virtual user (VU) runs the requests in the specified order in a repeating loop. All of the virtual users operate in parallel to simulate real-world load on your API.
The collection you use to develop and functionally test your API is also your load test. The pre-request and post-response scripts and pm.test() assertions you already wrote run under load the same way they do in a functional run. There’s no separate load-test script, tool, or language to maintain.
Choose where to run your performance test
You can start a performance run from the Postman app or the Postman CLI, using the same collection and configuration for each.
A performance test’s load originates in one of two places:
- Local runs generate load from the machine running the test, whether that’s your local machine or your CI/CD environment. Start one in the Postman app using the App run method, which is available in the desktop app only, or with the Postman CLI. Available on all plans.
- Cloud runs generate load from Postman’s managed infrastructure. They scale beyond what your local machine or CI/CD environment can produce, continue running after you close Postman or disconnect, and store detailed results for later comparison and sharing. Start one in the Postman app using the Cloud run method, or with the Postman CLI using the
--runner postman-cloudoption. Available on Solo, Team, and Enterprise plans.
Learn more about cloud performance tests and the system resources a local run needs.
Automate performance tests in CI/CD
Run the same performance test from the Postman CLI to catch performance regressions before they reach production. Set a success criterion with the --pass-if option, and the command exits with a non-zero code when your API misses it, which fails the build:
You can set the condition on average response time, the 90th, 95th, or 99th percentile, the error rate, or requests per second. To generate more load than your CI/CD environment can produce, add the --runner postman-cloud option to the same command. Because the command runs anywhere you can run a shell, you can also start it from a scheduled job to test unattended, such as each night against staging. Learn more about configuring and validating performance tests using the Postman CLI.
View real-time performance metrics
When you start a test, Postman displays performance metrics in real time as the test runs. If you identify a problem early in a cloud run, you can stop it to avoid billing for VU hours you don’t need.
Along with your API’s response times and error rates, Postman reports the peak CPU and memory usage of the machine generating the load. This helps you tell whether a latency spike came from your API or from the machine running the test. Learn more about viewing system metrics.
Cloud performance test runs consume VU hours, based on the number of virtual users in the run and the test’s duration.
You can view performance test metrics such as the average response time, error rate, and throughput for all requests or individual requests. You can also compare two performance runs to understand how your API’s performance has changed over time.
Find and debug performance issues
After the performance test finishes running, you can view details about failed test assertions and view details about errors that occurred during the test. You can view the most common error, failed test assertions, and trends over time to help you identify the source of any performance issues.
Because your collection’s pm.test() assertions run during the performance test, you can find correctness problems that only appear under load, such as stale cached reads, empty response bodies, or race conditions. The Tests vs VU view breaks assertion results down by virtual user level. Use it to identify which assertions fail first and at what point your API begins to break.
Use unique data for each virtual user
By default, each virtual user sends requests with the same data during a performance test. You can vary the behavior of virtual users to better simulate real-world traffic in two ways:
- Upload a data file — Use a CSV or JSON file with custom values for each virtual user.
- Use a dataset — Select a dataset shared across your collection runs and mocks.
Troubleshoot performance tests
To learn how to troubleshoot performance tests, see Troubleshoot performance tests in Postman.