Integrate your test suite with the Application Inventory

Postman’s Application Inventory integrates with your existing UI test suite to validate API interactions and discover dependencies automatically. This guide walks through setting up your first application and running tests with network capture.

The exact integration flow depends on whether you’re connecting your workspace or linking an application to an existing workspace. The key difference is that for new workspace connections, the setup process is guided and happens automatically when you link your repository.

For existing workspace connections, you need to create an application from the Application Inventory and run postman app test to complete the setup. To access the Application Inventory, click Home in the Postman sidebar and select Application Inventory.

Step 1: Link your application to a workspace

To connect your application repository to a Postman workspace, do the following:

1. Navigate to your Postman workspace.
2. If not already linked, connect your repository. From the Postman sidebar, click Files > Open folder. See Connect your Git project to your workspace for more details on Postman’s Git integration.
3. Complete the repository linking process.

If Postman detects Playwright tests in your code during the linking process, it automatically adds the application workspace tag to the Application Inventory.

Step 2: Install the Postman CLI

Install the latest version of the Postman CLI if you don’t already have it:

$
npm install -D postman-cli

Step 3: (Optional) Add API tests to your workspace

If you already have Postman Collections that represent your API contracts, add them to your workspace. To learn more about writing tests in Postman, see Write scripts to test API response data in Postman.

Step 4: Set up the capture plugin

You can set up capture automatically or manually:

• Automatically — Run postman app setup-capture. It installs the postman-playwright plugin and configures the recommended withPostman setup for you.
• Manually — If you’d rather set it up yourself, or if postman app setup-capture can’t update your Playwright configuration, follow the steps below to install the plugin and choose between the recommended withPostman setup and the alternative in-test-file setup.

Install the Postman Playwright plugin:

$
npm install -D postman-playwright

You can enable network capture in one of two ways. Postman recommends using withPostman because it requires only a one-time configuration change and works across all pages, contexts, and fixtures.

Recommended: Enable capture in your Playwright config

Add withPostman to your Playwright configuration:

1
// playwright.config.ts
2
import { defineConfig } from '@playwright/test';
3
import { withPostman } from 'postman-playwright';
4
5
export default withPostman(defineConfig({
6
  // Your existing Playwright configuration
7
}));

The withPostman function enables Playwright’s built-in JSON reporter and trace recording. The Postman CLI reads these artifacts (playwright-report.json and trace.zip) to analyze network traffic. No changes to your test code or custom data pipeline are required.

This approach requires only a one-time configuration change and provides broader capture coverage. However, test runs might take longer because Playwright must generate and store JSON reports and trace data.

Alternative: Enable capture in test files

You can also enable capture by wrapping Playwright’s test object with attachNetworkCapture:

1
import { test as baseTest, expect } from '@playwright/test';
2
import { attachNetworkCapture } from 'postman-playwright';
3
4
const test = attachNetworkCapture(baseTest);
5
6
test('has title', async ({ page }) => {
7
  await page.goto('https://playwright.dev/');
8
  await expect(page).toHaveTitle(/Playwright/);
9
});

This approach has lower runtime overhead because it doesn’t rely on Playwright trace artifacts. However, it requires updating each test file or creating a shared wrapper that re-exports the wrapped test object.

The attachNetworkCapture function only captures traffic from Playwright’s built-in page object. The function won’t capture traffic from pages created manually inside a test, such as pages created with browser.newContext() and context.newPage().

For example, network traffic from this manually created page won’t be captured by attachNetworkCapture:

1
test('creates a page manually', async ({ browser }) => {
2
  const context = await browser.newContext({
3
    recordVideo: { dir: './videos/' },
4
  });
5
6
  const page = await context.newPage();
7
});

Step 5: Run your application tests

Initialize your project if you haven’t already, optionally configure traffic filters, and run your tests with the Postman CLI.

Initialize your project

If the project isn’t initialized yet, run postman app test to walk through initialization interactively. The command creates a postman.config.cjs file in your project root, prompts you to select your test command and collections, and links your application to Postman. If you don’t have any existing API tests, you can generate a collection from the traffic captured during the run.

Filter out irrelevant traffic

To exclude irrelevant URLs, methods, and headers, update the filters configuration in postman.config.cjs. You can pass a single object (applied to all tests) or an array of scoped entries.

Single object that applies to all tests:

1
filters: {
2
  urlPatterns: ['fonts.googleapis.com', 'localhost:3007', 'fonts.gstatic.com'],
3
  methods: [],
4
  headers: {},
5
},

Scoped array where each filter can target specific tests by file path (target, matched as a regex) or Playwright tags (tags):

1
filters: [
2
  // Applied to all tests
3
  {
4
    urlPatterns: ['fonts.googleapis.com', 'fonts.gstatic.com'],
5
  },
6
  // Applied only to tests matching the path regex
7
  {
8
    target: 'tests/checkout\\.spec\\.ts',
9
    urlPatterns: ['sentry.io'],
10
  },
11
  // Applied only to tests tagged @checkout
12
  {
13
    tags: ['@checkout'],
14
    urlPatterns: ['analytics.example.com'],
15
  },
16
],

Each filter in the array is evaluated against the test. If a request matches any filter’s rules, it’s excluded from validation. Filters with no target or tags apply to all tests.

Run the tests

Run your UI tests using the Postman CLI:

$
postman app test

For local testing, use the --report-events option to capture test results and analytics in the Application Inventory:

$
postman app test --report-events

Collections and environments are selected from the targets defined in postman.config.cjs. You can override them at runtime using the --target, --target-environment, and --target-collection options.

You can use the --network-log option to analyze previously captured network traffic from a Playwright JSON report, network capture file, or artifact directory. This enables you to run validation and coverage analysis against a specific test run without relying on automatic artifact discovery.

Git metadata is automatically captured for each test run. This includes the commit ID, tags, parent commits, git describe output, Git notes, and whether the working tree has uncommitted changes. No additional configuration is required. This makes it possible to see which state of your codebase each test run relates to. In CI environments, the command also captures Git metadata from supported CI providers when available.

Git metadata describes the test run itself, not the build of the application that was deployed and served during the run. These often differ when your tests point at a shared, long-lived environment. To record which build a run tested, see Record the deployed version.

Results appear in the terminal. If you are logged in and the workspace has been added to the Application Inventory, results are also pushed to the Application Inventory.

Record the deployed version

To place your test runs on a deployment timeline in the Application Inventory, tell Postman which build of your application each run tested. You always supply this version yourself. Postman doesn’t infer it from your Git commit, because the commit your tests checked out isn’t necessarily the build that was deployed and served during the run.

Choose how to supply the version based on one question: did the run that tested your application also deploy it?

• The test run also deployed the build. Your pipeline deploys the build and then runs the tests against it, so it already knows the version. Pass it with the --deployed-version option, using whatever identifier the pipeline already has, such as a build ID, image tag, or commit. Add it after your deploy step:

  $
  postman app test --deployed-version "$BUILD_ID"

  For CI systems that assemble commands dynamically, set the APP_DEPLOYED_VERSION environment variable instead of passing the option.

• The test run didn’t deploy the build. Your tests run against an already-running environment, such as a shared staging environment or a scheduled suite pointed at production. Because the test run didn’t deploy that build, it can’t know the version. Read the version from the running application instead. Use Playwright’s globalSetup hook to fetch the version once before your tests run and store it in the report metadata:

  1
  // playwright.config.js
  2
  export default defineConfig({
  3
    globalSetup: './postman-version-setup.js',
  4
  });

  1
  // postman-version-setup.js
  2
  export default async function (config) {
  3
    const res = await fetch(`${process.env.BASE_URL}/version`);
  4
    const { version } = await res.json();
  5
    config.metadata['service.version'] = version;
  6
  }

This mode works only if your application exposes its version somewhere you can read at runtime. Whatever deployed the application is responsible for making the running build report the correct version. There’s no standard location, so adjust the probe to match your application. The version might come from a response header, a /version or /health endpoint, a <meta> tag, or a JavaScript global. Change only the line that reads the value so it points at wherever your application exposes it.

(Optional) Bootstrap collections from captured traffic

If you don’t have existing API tests, you can generate collections from observed network traffic:

$
postman app test --capture-only

This workflow:

• Captures traffic during UI test runs.
• Generates a draft Postman Collection from observed requests.
• Uses AI to help create assertions from captured responses.
• Allows you to refine the tests and reuse them in future runs.

The same UI traffic that validates your APIs can become the foundation for a comprehensive API contract suite.

Next steps

You can view your test results and discovered dependencies in the Application Inventory. Click Home in the Postman sidebar and select Application Inventory.