Skip to content
Postman API Testing Tips

How To Use Postman Agent

API Testing Blog

Understanding Postman Agents

Postman Agents are powerful tools for testing APIs in various environments, even those inaccessible from your local machine. They allow you to run your Postman collections directly on a remote server, providing a more realistic and efficient testing experience.

Prerequisites

Before diving into Postman Agents, ensure you have the following:

  • A Postman account: Sign up for a free account at https://www.postman.com/.
  • A Postman workspace: Create a workspace to organize your collections, environments, and agents.
  • A remote server with access: This could be a virtual machine, cloud instance, or any other server where you can run the Postman Agent.

Setting up a Postman Agent

  1. Install the Agent: Download the Postman Agent binary for your operating system from the Postman website.

  2. Configure the Agent:

    • Open the agent’s configuration file (typically config.json).
    • Set the authToken property to your Postman API key (found in your account settings).
    • Customize other options as needed:
      • logLevel: Specifies the logging level (e.g., INFO, DEBUG).
      • port: Sets the port used by the Agent (default: 5000).
      • workspaces: Defines the workspaces the Agent can access.

    Example config.json:

    {
      "authToken": "YOUR_POSTMAN_API_KEY",
      "logLevel": "INFO",
      "port": 5000,
      "workspaces": [
        "YOUR_WORKSPACE_ID"
      ]
    }

  3. Start the Agent: Run the Agent binary in a terminal/command prompt. It should be accessible on the configured port.

Using Postman Agents in Collections

  1. Create a Collection: Build your API test cases in a Postman collection.

  2. Add Environment Variables: Define your environment variables in the “Environments” tab in Postman. These variables can be accessed within your collection requests.

    • Important: Include variables like AGENT_HOST and AGENT_PORT to define the Agent’s address.

    • Example:

      {
        "id": "YOUR_ENVIRONMENT_ID",
        "name": "Agent Environment",
        "values": [
          { "key": "AGENT_HOST", "value": "YOUR_AGENT_HOST", "type": "text" },
          { "key": "AGENT_PORT", "value": "5000", "type": "text" }
        ]
      }

  3. Modify Request Headers:

    • In each request within your collection, add the header x-postman-agent-url.
    • Set its value to http://{{AGENT_HOST}}:{{AGENT_PORT}}/agent/v1/run.

    Example:

    "headers": [
      { "key": "x-postman-agent-url", "value": "http://{{AGENT_HOST}}:{{AGENT_PORT}}/agent/v1/run", "type": "text" }
    ]

  4. Run the Collection: Select the collection, choose your environment (“Agent Environment” in our example), and run it as usual.

    • Note: The runner will now execute the requests through the Postman Agent on the remote server.

Monitoring and Troubleshooting

  • Check the logs in the Agent’s directory for status updates and potential errors.
  • Use the Postman Agent Monitoring dashboard to monitor running agents, their status, and recent executions. You can access the dashboard through the Postman web app and navigate to “Agents” from the “Workspace” tab.
  • Inspect the response property in the Test tab for individual requests to verify the results obtained via the Agent. This helps pinpoint issues related to your API or the Agent.

Example: Testing a Remote API

Let’s say you have a remote endpoint on a server named api.example.com accessible only from within your network. Here’s how you can test it using a Postman Agent:

  1. Set up the Agent:

    • Download the Agent.
    • Configure the config.json with your API key and desired settings.
    • Start the Agent on the server.

  2. Create a Collection:

    • Create a request to https://api.example.com/v1/users.
    • Add the x-postman-agent-url header as described above.

  3. Environment Variables:

    • Create an environment named “RemoteAPI” with variables like: 
      {
        "id": "YOUR_ENVIRONMENT_ID",
        "name": "RemoteAPI",
        "values": [
          { "key": "AGENT_HOST", "value": "YOUR_AGENT_HOST", "type": "text" },
          { "key": "AGENT_PORT", "value": "5000", "type": "text" }
        ]
      }

  4. Run the Collection:

    • Select the collection and choose “RemoteAPI” as the environment.
    • Execute the collection.

    The requests will be sent through the Agent to the remote API, allowing you to test it effectively even from your local computer.

Why Use Postman Agents?

  • Realistic Testing: Agents run your tests on the actual server, providing accurate results and handling network configurations precisely.
  • Security and Privacy: Avoid exposing sensitive data on your local computer by running tests on a remote server.
  • Scaling and Automation: Easily scale your testing efforts by running multiple agents across different environments.
  • Integration with CI/CD Pipelines: Run tests as part of your continuous integration and continuous delivery (CI/CD) workflows, ensuring consistent API quality.

Conclusion

Postman Agents are an essential tool for testing APIs in diverse and challenging environments. By leveraging their remote execution capabilities, you can accurately test your APIs, improve their quality, and streamline your development process. Remember to experiment with different configurations and explore the various features of Postman Agents to unlock their full potential.

API Testing Blog