How to Use Newman with GitHub Actions in Postman

Use newman to run Postman collections in GitHub Actions by adding a workflow YAML file that installs Node.js, installs Newman, and runs your collection with newman run. This automates your API tests on every push or pull request.

Syntax

The basic syntax to run a Postman collection with Newman in GitHub Actions involves these steps:

• Set up Node.js environment: Use actions/setup-node to install Node.js.
• Install Newman: Run npm install -g newman to get Newman globally.
• Run the collection: Use newman run <collection-file.json> to execute your tests.

This syntax is placed inside a GitHub Actions workflow YAML file under the jobs section.

yaml

name: Run Postman Tests

on: [push, pull_request]

jobs:
  test_api:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repo
        uses: actions/checkout@v3

      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'

      - name: Install Newman
        run: npm install -g newman

      - name: Run Postman Collection
        run: newman run ./postman_collection.json

Example

This example shows a complete GitHub Actions workflow that runs a Postman collection named postman_collection.json on every push or pull request. It checks out the code, sets up Node.js, installs Newman, and runs the collection.

yaml

name: Postman API Tests

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  run-newman:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v3

      - name: Setup Node.js environment
        uses: actions/setup-node@v3
        with:
          node-version: '18'

      - name: Install Newman globally
        run: npm install -g newman

      - name: Run Postman collection
        run: newman run ./postman_collection.json --reporters cli,junit --reporter-junit-export results.xml

Output

newman
→ starting run: ./postman_collection.json

┌─────────────────────────┐
│                         │
│  newman summary         │
│                         │
├─────────────┬───────────┤
│ iterations  │ 1         │
│ requests    │ 5         │
│ test scripts│ 5         │
│ assertions  │ 10        │
│ failures   │ 0         │
│ skipped    │ 0         │
└─────────────┴───────────┘

newman run completed successfully.

Common Pitfalls

Common mistakes when using Newman with GitHub Actions include:

• Not checking out the repository before running Newman, causing missing collection files.
• Forgetting to install Node.js or Newman, leading to command not found errors.
• Using incorrect paths to the Postman collection JSON file.
• Not specifying the correct Node.js version, which may cause compatibility issues.

Always verify your collection file is committed and the path is correct relative to the workflow root.

yaml

name: Incorrect Workflow Example

on: push

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - name: Run Newman without checkout
        run: newman run ./postman_collection.json

# Corrected version
name: Correct Workflow Example

on: push

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '18'
      - run: npm install -g newman
      - run: newman run ./postman_collection.json

Quick Reference

Tips for using Newman with GitHub Actions:

• Always use actions/checkout@v3 to get your code.
• Use actions/setup-node@v3 to install Node.js (version 18 or later recommended).
• Install Newman globally with npm install -g newman.
• Run your collection with newman run <collection-file.json>.
• Use reporters like cli and junit for readable output and integration with CI tools.

Key Takeaways

Always checkout your repository before running Newman in GitHub Actions.

Set up Node.js environment using the official GitHub Action before installing Newman.

Run Newman with the correct path to your Postman collection JSON file.

Use reporters in Newman to generate useful test reports in CI pipelines.

Test your workflow locally or in a test branch to catch configuration errors early.