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

Practice

1. What is the main purpose of custom documentation templates in Postman?

easy

A. To control the appearance and structure of API documentation

B. To write test scripts for API requests

C. To automate API request execution

D. To generate API mock servers

Solution

1. Step 1: Understand the role of documentation templates

   Custom documentation templates let you change how API docs look and feel, making them clearer and tailored.

2. Step 2: Differentiate from other Postman features

   Test scripts, automation, and mock servers serve different purposes unrelated to documentation appearance.

3. Final Answer:

   To control the appearance and structure of API documentation -> Option A

4. Quick Check:

   Custom templates = control doc look [OK]

Hint: Templates change docs look, not tests or mocks [OK]

Common Mistakes:

• Confusing templates with test scripts
• Thinking templates automate requests
• Mixing templates with mock server setup

2. Which syntax is used inside Postman custom documentation templates to insert dynamic content?

easy

A. [[variable]]

B. {{variable}}

C. %%variable%%

D. ##variable##

Solution

1. Step 1: Identify the templating syntax used by Postman

   Postman uses Handlebars syntax, which uses double curly braces like {{variable}} to insert dynamic content.

2. Step 2: Compare with other common syntaxes

   Other options like [[ ]], %% %% or ## ## are not used in Postman templates.

3. Final Answer:

   {{variable}} -> Option B

4. Quick Check:

   Handlebars = {{variable}} [OK]

Hint: Remember Handlebars uses double curly braces {{}} [OK]

Common Mistakes:

• Using square brackets instead of curly braces
• Confusing with environment variable syntax
• Using percent signs or hashes incorrectly

3. Given this snippet in a Postman custom documentation template:

{{#each requests}}
- {{name}}
{{/each}}

What will this code output?

medium

A. The word 'requests' repeated multiple times

B. An error because loops are not allowed

C. A list of request names from the collection

D. Nothing, because {{name}} is undefined

Solution

1. Step 1: Understand the Handlebars loop syntax

   The {{#each requests}} block loops over all requests in the collection, outputting each request's name.

2. Step 2: Determine the output of the loop

   Each iteration outputs a dash and the request name, creating a list of request names.

3. Final Answer:

   A list of request names from the collection -> Option C

4. Quick Check:

   Loop over requests outputs names [OK]

Hint: Loops with #each output list items [OK]

Common Mistakes:

• Thinking loops are not supported
• Assuming {{name}} is undefined
• Expecting repeated static text instead of dynamic names

4. You wrote this in a Postman custom documentation template:

{{#each requests}}
- {{name}
{{/each}}

Why does the documentation fail to render correctly?

medium

A. Incorrect loop syntax, should be {{#for requests}}

B. The closing tag {{/each}} is missing

C. The variable 'name' does not exist in requests

D. Missing closing curly brace in {{name}}

Solution

1. Step 1: Check the variable syntax inside the loop

   The variable {{name} is missing a closing curly brace, it should be {{name}}.

2. Step 2: Verify loop syntax and tags

   The loop uses correct {{#each requests}} and closing {{/each}} tags, so those are not the issue.

3. Final Answer:

   Missing closing curly brace in {{name}} -> Option D

4. Quick Check:

   All must have matching braces [OK]

Hint: Check all {{}} pairs are closed properly [OK]

Common Mistakes:

• Using wrong loop syntax like #for
• Assuming variable 'name' is missing
• Forgetting to close the loop tag

5. You want to create a custom documentation template that shows each request's name and description only if the description exists. Which Handlebars syntax correctly achieves this?

hard

A. {{#each requests}}
- {{name}}
{{#if description}}
Description: {{description}}
{{/if}}
{{/each}}

B. {{#each requests}}
- {{name}}
{{#unless description}}
Description: {{description}}
{{/unless}}
{{/each}}

C. {{#each requests}}
- {{name}}
{{#if !description}}
Description: {{description}}
{{/if}}
{{/each}}

D. {{#each requests}}
- {{name}}
{{#exists description}}
Description: {{description}}
{{/exists}}
{{/each}}

Solution

1. Step 1: Use the correct conditional block for existence

   Handlebars uses {{#if variable}} to check if a variable exists and is truthy.

2. Step 2: Verify the loop and conditional structure

   {{#each requests}}
   - {{name}}
   {{#if description}}
     Description: {{description}}
   {{/if}}
   {{/each}}

   correctly loops over requests, shows name, and conditionally shows description only if it exists.

3. Final Answer:

   {{#each requests}} - {{name}} {{#if description}} Description: {{description}} {{/if}} {{/each}} -> Option A

4. Quick Check:

   Use {{#if}} to check existence [OK]

Hint: Use {{#if variable}} to show content only if it exists [OK]

Common Mistakes:

• Using {{#unless}} which shows content when variable is missing
• Trying to negate with ! inside {{#if}} which is invalid
• Using non-existent helpers like {{#exists}}