0
0
Postmantesting~8 mins

Request descriptions and documentation in Postman - Framework Patterns

Choose your learning style9 modes available
Framework Mode - Request descriptions and documentation
Folder Structure
Postman Collection
├── Folder: User Management
│   ├── Request: Create User
│   ├── Request: Get User
│   └── Request: Delete User
├── Folder: Authentication
│   ├── Request: Login
│   └── Request: Logout
└── Folder: Utilities
    └── Request: Health Check

This structure organizes requests into folders by feature or API area.

Test Framework Layers
  • Collection Layer: Groups related API requests into folders for clarity.
  • Request Layer: Individual API calls with method, URL, headers, body, and tests.
  • Pre-request Scripts: JavaScript code run before requests to set variables or environment data.
  • Test Scripts: JavaScript assertions to validate response data and status codes.
  • Environment Layer: Holds variables like base URLs, tokens, credentials for different environments.
  • Documentation Layer: Descriptions and examples attached to collections, folders, and requests.
Configuration Patterns
  • Environment Variables: Use Postman environments to store base URLs, API keys, and credentials for dev, test, and prod.
  • Global Variables: For values shared across collections like common headers or tokens.
  • Collection Variables: Scoped to a collection for reusable data like endpoint paths.
  • Pre-request Scripts: Dynamically set or update variables before requests run.
  • Documentation Fields: Use the description field in collections, folders, and requests to explain purpose, parameters, and expected results.
Test Reporting and CI/CD Integration
  • Postman Test Results: View pass/fail status and detailed assertion messages in the Postman app after running requests or collections.
  • Newman CLI: Run Postman collections from command line with detailed JSON or HTML reports.
  • CI/CD Integration: Integrate Newman runs into pipelines (Jenkins, GitHub Actions) to automate API tests on code changes.
  • Documentation Publishing: Use Postman's built-in documentation generator to publish API docs accessible to the team.
Best Practices
  • Write Clear Descriptions: Add meaningful descriptions to collections, folders, and requests to explain their purpose and usage.
  • Use Examples: Attach example requests and responses to help understand expected behavior.
  • Keep Documentation Updated: Regularly update descriptions and examples when API changes occur.
  • Use Environment Variables: Avoid hardcoding URLs or credentials; use variables for flexibility and security.
  • Organize Requests Logically: Group related requests in folders to make navigation and understanding easier.
Self Check

Where in this Postman collection structure would you add a detailed explanation about the authentication flow?

Key Result
Organize API requests into collections with clear descriptions and examples, use environment variables for configuration, and integrate Newman for automated test reporting.