Step-by-Step: Building Automated API Tests with Postman 11.0 and GitHub Actions 3.0

// Import required dependencies for Newman 6.0 (compatible with Postman 11.0 collections)
const newman = require('newman');
const fs = require('fs');
const path = require('path');
const { promisify } = require('util');

// Promisify fs methods for async/await error handling
const writeFileAsync = promisify(fs.writeFile);
const mkdirAsync = promisify(fs.mkdir);

// Configuration constants - adjust these for your project
const POSTMAN_COLLECTION_PATH = path.join(__dirname, 'postman', 'api-tests.postman_collection.json');
const POSTMAN_ENV_PATH = path.join(__dirname, 'postman', 'staging.postman_environment.json');
const REPORTS_DIR = path.join(__dirname, 'test-reports', 'newman');
const COLLECTION_SCHEMA_VERSION = '2.1.0'; // Postman 11.0 uses 2.1.0 schema

/**
 * Validates that required Postman files exist before execution
 * @throws {Error} If collection or environment file is missing
 */
function validatePostmanFiles() {
    if (!fs.existsSync(POSTMAN_COLLECTION_PATH)) {
        throw new Error(`Postman collection not found at ${POSTMAN_COLLECTION_PATH}. Run 'postman collection export' first.`);
    }
    if (!fs.existsSync(POSTMAN_ENV_PATH)) {
        throw new Error(`Postman environment not found at ${POSTMAN_ENV_PATH}. Create a staging environment in Postman 11.0.`);
    }
}

/**
 * Runs the Postman collection via Newman with error handling and reporting
 * @returns {Promise}
 */
async function runPostmanTests() {
    try {
        // Validate input files first
        validatePostmanFiles();

        // Create reports directory if it doesn't exist
        if (!fs.existsSync(REPORTS_DIR)) {
            await mkdirAsync(REPORTS_DIR, { recursive: true });
            console.log(`Created test reports directory at ${REPORTS_DIR}`);
        }

        // Execute Newman run with all required reporters
        newman.run({
            collection: require(POSTMAN_COLLECTION_PATH),
            environment: require(POSTMAN_ENV_PATH),
            reporters: ['cli', 'json', 'html'],
            reporter: {
                json: {
                    export: path.join(REPORTS_DIR, 'newman-report.json'),
                },
                html: {
                    export: path.join(REPORTS_DIR, 'newman-report.html'),
                    template: path.join(__dirname, 'postman', 'html-template.hbs') // Custom template for CI
                }
            },
            timeout: 30000, // 30s timeout per request
            delayRequest: 100, // 100ms delay between requests to avoid rate limiting
            iterationCount: 1, // Run all test cases once
        }, (err, summary) => {
            if (err) {
                console.error('Newman execution failed:', err);
                process.exit(1);
            }

            // Log test summary to console
            const { failures, stats } = summary;
            console.log(`Test run complete: ${stats.tests.total} total tests, ${stats.tests.failed} failed, ${stats.tests.passed} passed`);

            if (failures.length > 0) {
                console.error(`❌ ${failures.length} test failures detected:`);
                failures.forEach((failure, idx) => {
                    console.error(`  ${idx + 1}. ${failure.source.name}: ${failure.error.message}`);
                });
                process.exit(1);
            } else {
                console.log('✅ All Postman API tests passed!');
                process.exit(0);
            }
        });
    } catch (error) {
        console.error('Fatal error during test setup:', error.message);
        process.exit(1);
    }
}

// Execute the test runner
runPostmanTests();

# GitHub Actions 3.0 Workflow for Automated Postman API Tests
# Trigger on PRs to main, and pushes to main
name: Postman API Tests

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]
  # Allow manual triggers for debugging
  workflow_dispatch:

# Set environment variables for all jobs
env:
  NODE_VERSION: '20.x'
  POSTMAN_COLLECTION_PATH: ./postman/api-tests.postman_collection.json
  POSTMAN_ENV_PATH: ./postman/staging.postman_environment.json
  NEWMAN_VERSION: '6.0.0' # Compatible with Postman 11.0 collections

jobs:
  run-api-tests:
    runs-on: ubuntu-latest
    # GitHub Actions 3.0 allows nested job matrices for parallel test runs
    strategy:
      matrix:
        # Run tests against staging and dev environments in parallel
        environment: [staging, dev]
      fail-fast: false # Continue other matrix jobs if one fails

    steps:
      - name: Checkout Repository
        uses: actions/checkout@v4 # GitHub Actions 3.0 compatible
        with:
          fetch-depth: 0 # Fetch all history for proper caching

      - name: Setup Node.js ${{ env.NODE_VERSION }}
        uses: actions/setup-node@v4
        with:
          node-version: ${{ env.NODE_VERSION }}
          cache: 'npm' # Cache npm dependencies to speed up runs

      - name: Install Newman and Reporters
        run: |
          npm install -g newman@${{ env.NEWMAN_VERSION }}
          npm install -g newman-reporter-html newman-reporter-json
        # Continue if install fails, but log error
        continue-on-error: false

      - name: Validate Postman Files Exist
        run: |
          if [ ! -f "${{ env.POSTMAN_COLLECTION_PATH }}" ]; then
            echo "::error::Postman collection not found at ${{ env.POSTMAN_COLLECTION_PATH }}"
            exit 1
          fi
          if [ ! -f "${{ env.POSTMAN_ENV_PATH }}" ]; then
            echo "::error::Postman environment not found at ${{ env.POSTMAN_ENV_PATH }}"
            # For dev environment, use staging env as fallback
            if [ "${{ matrix.environment }}" = "dev" ]; then
              echo "::warning::Using staging environment for dev test run"
              cp ./postman/staging.postman_environment.json ./postman/dev.postman_environment.json
            else
              exit 1
            fi
          fi
        # Always run this step to catch missing files early
        if: always()

      - name: Run Postman Tests with Newman
        run: |
          mkdir -p ./test-reports/${{ matrix.environment }}
          newman run ${{ env.POSTMAN_COLLECTION_PATH }} \
            --environment ./postman/${{ matrix.environment }}.postman_environment.json \
            --reporters cli,json,html \
            --reporter-json-export ./test-reports/${{ matrix.environment }}/newman-report.json \
            --reporter-html-export ./test-reports/${{ matrix.environment }}/newman-report.html \
            --timeout-request 30000 \
            --delay-request 100
        # Capture exit code to handle failures gracefully
        id: newman-run
        continue-on-error: true

      - name: Upload Test Reports as Artifacts
        uses: actions/upload-artifact@v4
        with:
          name: postman-test-reports-${{ matrix.environment }}
          path: ./test-reports/${{ matrix.environment }}/*
          retention-days: 30 # Keep reports for 30 days per GitHub Actions 3.0 policy
        # Always upload reports even if tests fail
        if: always()

      - name: Notify on Test Failure
        if: steps.newman-run.outcome == 'failure'
        uses: actions/github-script@v7
        with:
          script: |
            const { repo, owner } = context.repo;
            const runId = context.runId;
            const env = '${{ matrix.environment }}';
            const message = `❌ Postman API tests failed in ${env} environment. [View Run](https://github.com/${owner}/${repo}/actions/runs/${runId})`;
            // Create a PR comment if this is a PR run
            if (context.eventName === 'pull_request') {
              const prNumber = context.payload.pull_request.number;
              await github.rest.issues.createComment({
                owner,
                repo,
                issue_number: prNumber,
                body: message
              });
            }
            console.log(message);

      - name: Fail Job if Tests Failed
        if: steps.newman-run.outcome == 'failure'
        run: |
          echo "::error::Postman tests failed in ${{ matrix.environment }}. Check uploaded artifacts."
          exit 1

// Slack notification script for Postman test results (compatible with GitHub Actions 3.0)
const { IncomingWebhook } = require('@slack/webhook');
const fs = require('fs');
const path = require('path');

// Configuration - set these as GitHub Actions secrets
const SLACK_WEBHOOK_URL = process.env.SLACK_WEBHOOK_URL;
const GITHUB_REPO = process.env.GITHUB_REPOSITORY;
const GITHUB_RUN_ID = process.env.GITHUB_RUN_ID;
const ENVIRONMENT = process.env.TEST_ENVIRONMENT || 'staging';
const REPORT_PATH = process.env.NEWMAN_REPORT_PATH || './test-reports/newman-report.json';

/**
 * Validates required environment variables are set
 * @throws {Error} If required vars are missing
 */
function validateEnvVars() {
    const requiredVars = ['SLACK_WEBHOOK_URL', 'GITHUB_REPOSITORY', 'GITHUB_RUN_ID'];
    const missingVars = requiredVars.filter(varName => !process.env[varName]);
    if (missingVars.length > 0) {
        throw new Error(`Missing required environment variables: ${missingVars.join(', ')}. Set these in GitHub Actions secrets.`);
    }
    if (!fs.existsSync(REPORT_PATH)) {
        throw new Error(`Newman report not found at ${REPORT_PATH}. Run tests first.`);
    }
}

/**
 * Parses Newman JSON report to extract test metrics
 * @param {string} reportPath - Path to Newman JSON report
 * @returns {Object} Test metrics (total, passed, failed, skipped)
 */
function parseNewmanReport(reportPath) {
    try {
        const report = JSON.parse(fs.readFileSync(reportPath, 'utf8'));
        const { stats, failures } = report.run;
        return {
            total: stats.tests.total,
            passed: stats.tests.passed,
            failed: stats.tests.failed,
            skipped: stats.tests.skipped,
            failures: failures || []
        };
    } catch (error) {
        throw new Error(`Failed to parse Newman report: ${error.message}`);
    }
}

/**
 * Sends Slack notification with test results
 * @param {Object} metrics - Test metrics from parseNewmanReport
 * @returns {Promise}
 */
async function sendSlackNotification(metrics) {
    try {
        const webhook = new IncomingWebhook(SLACK_WEBHOOK_URL);
        const runUrl = `https://github.com/${GITHUB_REPO}/actions/runs/${GITHUB_RUN_ID}`;
        const statusEmoji = metrics.failed > 0 ? '❌' : '✅';
        const statusText = metrics.failed > 0 ? 'FAILED' : 'PASSED';

        const blocks = [
            {
                type: 'header',
                text: {
                    type: 'plain_text',
                    text: `${statusEmoji} Postman API Tests ${statusText} (${ENVIRONMENT})`,
                    emoji: true
                }
            },
            {
                type: 'section',
                fields: [
                    { type: 'mrkdwn', text: `*Repository:*
${GITHUB_REPO}` },
                    { type: 'mrkdwn', text: `*Environment:*
${ENVIRONMENT}` },
                    { type: 'mrkdwn', text: `*Total Tests:*
${metrics.total}` },
                    { type: 'mrkdwn', text: `*Passed:*
${metrics.passed}` },
                    { type: 'mrkdwn', text: `*Failed:*
${metrics.failed}` },
                    { type: 'mrkdwn', text: `*Skipped:*
${metrics.skipped}` }
                ]
            },
            {
                type: 'section',
                text: {
                    type: 'mrkdwn',
                    text: `*View Full Results:* <${runUrl}|GitHub Actions Run>`
                }
            }
        ];

        // Add failure details if any
        if (metrics.failures.length > 0) {
            const failureText = metrics.failures.slice(0, 5).map((f, idx) => 
                `${idx + 1}. ${f.source.name}: ${f.error.message}`
            ).join('
');
            blocks.push({
                type: 'section',
                text: {
                    type: 'mrkdwn',
                    text: `*Top Failures:*
${failureText}`
                }
            });
        }

        await webhook.send({ blocks });
        console.log('Slack notification sent successfully');
    } catch (error) {
        console.error('Failed to send Slack notification:', error.message);
        process.exit(1);
    }
}

/**
 * Main execution function
 */
async function main() {
    try {
        validateEnvVars();
        const metrics = parseNewmanReport(REPORT_PATH);
        await sendSlackNotification(metrics);
        process.exit(0);
    } catch (error) {
        console.error('Fatal error:', error.message);
        process.exit(1);
    }
}

// Run the script
main();

// Validate response body against OpenAPI 3.1 schema
pm.test('Response matches API schema', () => {
    const schema = {
        type: 'object',
        required: ['id', 'name', 'createdAt'],
        properties: {
            id: { type: 'string', format: 'uuid' },
            name: { type: 'string', minLength: 1 },
            createdAt: { type: 'string', format: 'date-time' },
            status: { type: 'string', enum: ['active', 'inactive'] }
        }
    };
    pm.response.to.have.jsonSchema(schema);
});

- name: Cache Newman Dependencies
  uses: actions/cache@v4
  with:
    path: ~/.npm/_npx # Cache global npm packages
    key: ${{ runner.os }}-newman-${{ env.NEWMAN_VERSION }}
    restore-keys: |
      ${{ runner.os }}-newman-

{
    "id": "staging-env-123",
    "name": "Staging",
    "values": [
        { "key": "base_url", "value": "https://api-staging.example.com", "type": "text" },
        { "key": "api_key", "value": "${{ secrets.STAGING_API_KEY }}", "type": "secret" },
        { "key": "rate_limit", "value": "100", "type": "number" }
    ]
}

postman-github-actions-demo/
├── .github/
│   └── workflows/
│       └── postman-tests.yml       # GitHub Actions 3.0 workflow
├── postman/
│   ├── api-tests.postman_collection.json  # Postman 11.0 collection
│   ├── staging.postman_environment.json   # Staging environment
│   ├── dev.postman_environment.json       # Dev environment
│   └── html-template.hbs                  # Custom Newman HTML report template
├── scripts/
│   ├── run-newman-tests.js                # Local Newman test runner
│   └── send-slack-notification.js         # Slack alert script
├── test-reports/                          # Generated test reports (gitignored)
├── package.json                           # Node.js dependencies
└── README.md                              # Setup instructions