Postman CLI app commands (postman app)
Postman CLI app commands (postman app)
Application Inventory is available on Postman Solo, Team, and Enterprise plans. For more information, see the pricing page.
You can use the Postman CLI to run UI tests with network capture, validate observed API traffic against Postman Collections, and send results to Postman’s Application Inventory. The postman app commands require the repository to be linked to a Postman workspace (Git-connected).
postman app test
This command runs your application’s existing UI test command, captures the network traffic generated during the run, and validates observed API calls against requests in your collections. For matched calls, the command runs the pm.test assertions defined in the collection against the observed responses. It also reports unmatched calls and coverage gaps.
If the project isn’t configured yet, running postman app test for the first time walks you through setup interactively, including creating a postman.config.cjs file and selecting your collections. The command requires the capture plugin to be installed. You can install it with npm install postman-playwright and configure it manually, or let the interactive setup guide you through it.
Reporting results to the Application Inventory requires the repository to be connected to a Postman workspace. If reporting is enabled and no workspace is connected yet, the command walks you through connecting one. You can create a new workspace, select or search for an existing one, or enter a workspace ID. In CI and other non-interactive environments, the command prints setup instructions and exits so you can connect a workspace before running again.
When configured, the command also sends test results and detected dependencies to the Application Inventory. Learn more about using postman app test to run your application’s UI tests.
To use this command with persistent data in the cloud, sign in to Postman with the postman login command.
Usage
Options
UI test command to run.
A named runtime setup in postman.config.cjs (such as default, staging, or prod) that selects which collections and environment a given test run uses.
Override the collection defined in the selected target.
Override the environment defined in the selected target.
Capture traffic without validation and generate a draft collection from the observed requests. Each run overwrites the output directory, so you can run --capture-only again without first clearing it.
Capture traffic from the test run, generate a collection from it, then validate the same run against that collection. Postman writes a test for each captured API endpoint. Each test asserts the status codes observed during the capture and the shape of each JSON response body. It also sets a response time limit of twice the slowest successful response, or 5000 ms when none was observed. Requests to development-server paths and browser assets, such as scripts, stylesheets, and images, don’t get a test. Postman saves the collection to postman.config.cjs only when the selected target lists no collections.
Take the default for every setup question instead of prompting. Postman generates a collection from test traffic when the target lists none, and installs the capture plugin when it isn’t already set up. This option doesn’t cover connecting a Postman workspace. That step still prompts in an interactive terminal.
Deprecated. Kept as a no-op for backward compatibility. The output directory used with --capture-only is always overwritten on each run, so this option no longer has any effect.
Path to the captured network traffic artifacts to analyze. You can provide a Playwright JSON report file, a network capture file, or a directory with supported artifacts. When a directory is provided, Postman automatically discovers Playwright reports, associated traces, and network capture files. By default, Postman searches the Playwright outputDir, test-results/, and pm-results/ directories.
Directory where the captured collection is written when using the --capture-only option.
Reports application test results to the API Catalog and Application Inventory by default. To turn this off, pass --report-events=false. You can also use --no-report-events.
The version of the deployed application the run tested, such as a build ID, image tag, or semver string. Postman records this with the run so you can place runs on a deployment timeline in the Application Inventory. You supply this value yourself. Postman doesn’t infer it from your Git commit. Instead of passing this option, you can set the APP_DEPLOYED_VERSION environment variable. Learn more about recording the deployed version.
Show detailed per-request matching and execution logging.
Workflow
-
Run UI tests — Runs the UI test command defined in
postman.config.cjs. If you provide the--network-logoption, Postman analyzes the specified capture artifacts instead of relying on automatic artifact discovery. -
Capture traffic — Observes the network requests and responses generated during the run, or loads them from the specified network log artifacts.
-
Match requests — Maps captured calls to requests in the configured collections using method, path, query, and optional body hints.
-
Validate responses — Runs
pm.testassertions on matched responses. -
Report results — Reports assertion failures, unmatched calls, and coverage gaps. Git metadata for the commit is also captured automatically and reported with the run. Git metadata includes tags, parent commits,
git describeoutput, Git notes, and working tree state. When configured, the command also sends results and detected dependencies to the Application Inventory.The matched-request count breaks down into requests with assertions and requests without, such as
32 matched (9 with tests, 23 without). This breakdown appears only when at least one matched request produced no assertions, so a run where every matched request has at least one assertion is unaffected. Collection items with test scripts that contain nopm.test()calls count as matched but without tests, so you can tell them apart from calls that failed to match at all.
Configuration
The postman app test command expects a postman.config.cjs file in your working directory.
The configuration file defines the targets used during a run. Each target can specify a collection and an environment. You can override those values at runtime with --target-collection and --target-environment.
You can also use the filters section in postman.config.cjs to exclude noisy traffic from validation, such as font requests, localhost traffic, or other requests that aren’t part of your API surface. Filters can be a single object (applied to all tests) or an array of scoped entries, each targeting specific tests by file path or Playwright tag. Learn how to filter out irrelevant traffic.
Run without prompts
When there’s no interactive terminal, such as in a CI job or when input is piped, the command doesn’t prompt for setup. It uses the options you pass instead, and stops rather than waiting for an answer:
- If the selected target lists no collection, the command exits with code
2. The error names--target-collectionand--generate-collection. - If no test command is set and Postman finds no Playwright configuration file, the command exits with code
2. The error names--command. - If no test command is set and Postman finds a Playwright configuration file, the command runs
npx playwright test. - If the capture plugin isn’t set up, the command exits with code
2.
Pass --yes to take the default for each of these instead of stopping.
Examples
postman app setup-capture
This command sets up automatic network traffic capture for your Playwright tests. It installs the postman-playwright package as a development dependency if needed, and patches your Playwright configuration file to wrap its default export with withPostman(). This enables postman app test to capture the network traffic generated during your test runs.
If the command can’t patch your configuration automatically, it prints the manual setup steps instead.
The command exits with code 1 when it can’t complete setup. This covers finding no Playwright configuration file, a --config path that’s missing or isn’t a Playwright configuration file, and a failed package install or configuration patch.
Usage
Options
The path to the Playwright configuration file to patch. By default, the command auto-detects it.
Install the package and patch the configuration file without asking for confirmation. Required outside an interactive terminal, where the command otherwise makes no changes and exits with code 2.
Show the current capture setup and list what the command would install or patch, without changing any files. The command exits with code 0 when it finds a configuration file to report on, and it takes precedence over --yes.
Examples
postman app init
The postman app init command is deprecated. Use the postman app test command instead, which handles project initialization automatically on first run.
This command initializes application testing in the current repository by creating a postman.config.cjs file in your project’s root directory. Use the configuration file to define the targets, collections, environments, and filters used during application test runs. Targets enable you to select different collections and environments for different runtime setups, such as default, staging, or prod.
To use this command with persistent data in the cloud, sign in to Postman with the postman login command.