Custom documentation templates in Postman - Build an Automation Script

Automate verification of custom documentation template rendering in Postman

Preconditions (3)

Step 1: Open the Postman application

Step 2: Navigate to the Collections tab

Step 3: Select the collection with the custom documentation template

Step 4: Click on the 'View Documentation' button

Step 5: Verify that the documentation page loads

Step 6: Check that the custom template elements (e.g., custom header, footer, or styling) are present

Step 7: Verify that the request details (URL, method, headers, body) are correctly displayed according to the custom template

✅ Expected Result: The documentation page loads successfully showing the custom template elements and the request details formatted as per the custom template

Automation Requirements - Postman test scripts with Newman CLI

Assertions Needed:

Verify HTTP status code 200 for documentation page request

Verify presence of custom template elements in the documentation HTML

Verify request details are correctly displayed in the documentation

Best Practices:

Use Newman CLI to run collection and export documentation

Use JSON schema validation for response structure

Use environment variables for dynamic data

Avoid hardcoding URLs; use collection variables

Use descriptive assertion messages

Automated Solution

Postman

const newman = require('newman');

newman.run({
    collection: './MyCollection.json',
    environment: './MyEnvironment.json',
    reporters: ['cli'],
    reporter: {
        cli: { noFailures: true }
    }
}, function (err, summary) {
    if (err) { throw err; }
    // Check that all requests passed
    const failures = summary.run.failures;
    if (failures.length > 0) {
        console.error('Test failures:', failures);
        process.exit(1);
    }
    // Simulate fetching documentation page (assuming hosted locally or via API)
    const fetch = require('node-fetch');
    const documentationUrl = 'http://localhost:3000/docs/MyCollection';

    fetch(documentationUrl)
        .then(res => {
            if (res.status !== 200) {
                throw new Error(`Expected status 200 but got ${res.status}`);
            }
            return res.text();
        })
        .then(html => {
            if (!html.includes('<header class="custom-header">')) {
                throw new Error('Custom header not found in documentation');
            }
            if (!html.includes('GET /users')) {
                throw new Error('Request details not found in documentation');
            }
            console.log('Custom documentation template verified successfully');
        })
        .catch(err => {
            console.error('Error verifying documentation:', err.message);
            process.exit(1);
        });
});

This script uses Newman, the Postman CLI tool, to run the collection tests first to ensure the API requests work as expected.

After the collection run, it fetches the documentation page URL where the custom template is applied.

It asserts the HTTP status code is 200 to confirm the page loads successfully.

Then it checks the HTML content for the presence of custom template elements like a custom header and the expected request details.

If any assertion fails, the script throws an error and exits with failure.

This approach ensures both the API and the custom documentation template are verified automatically.

Common Mistakes - 3 Pitfalls

Hardcoding documentation URLs without using variables

Not waiting for documentation page to fully load before assertions

Checking only for HTTP status without verifying content

Bonus Challenge

Now add data-driven testing with 3 different collections each having different custom documentation templates

Show Hint