Welcome to TWIL, your weekly digest of micro-learning! This edition, Emily takes us on a journey with Newman, a CLI Collection Runner for Postman! Discover the power of running Postman collections via the command line, integrating API tests into your CI/CD pipelines, and the seamless usage of environmental variables. Dive into the JSON configurations and shell commands that streamline your testing workflow, all brought to life with real-world examples straight from the Cuttlesoft playbook.
Newman, a CLI Collection Runner for Postman!
Run Postman collections from the command line!
Install with npm: npm install -g newman
The export a collection from directly from Postman (choose Collection v2.1), or pass a collection URL once you’ve shared it.
The collection file is just a JSON that looks like this:
{
"info": {
"_postman_id": "7473c4ef-8fbd-4b69-98be-81b2c5542b42",
"name": "cuttlesoft.com",
"schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json",
"_exporter_id": "149617"
},
"item": [
{
"name": "Query MediaItem",
"request": {
"method": "POST",
"header": [],
"body": {
"mode": "graphql",
"graphql": {
"query": "query MediaItem {\n mediaItem(id: 15141, idType: DATABASE_ID) {...}",
"variables": ""
}
},
"url": {
"raw": "{{baseURL}}/graphql",
"host": [
"{{baseURL}}"
],
"path": [
"graphql"
]
}
},
"response": []
},
]
}Caveat: if you use environment variables, you need to pass them to newman — but you can also export environments by going to:Environments → Select an Environment → Right-Click and Select Export.
This creates a json file that looks like this:
{
"id": "dae9890f-dc49-41a4-8be7-e34dd24d7010",
"name": "cuttlesoftcom.local",
"values": [
{
"key": "baseURL",
"value": "https://cuttlesoftcom.local",
"type": "default",
"enabled": true
},
{
"key": "wpAuthorization",
"value": "randomGeneratedPassword",
"type": "secret",
"enabled": true
}
],
"_postman_variable_scope": "environment",
"_postman_exported_at": "2024-01-24T20:40:59.538Z",
"_postman_exported_using": "Postman/10.19.17"
}Which you then pass to newman with the -e flag:
newman run cuttlesoftcom.postman_collection.json -e cuttlesoftcom.local.postman_environment.jsonUse on CI
One of the advantages to Postman’s newman tool is that it can be installed on CI and used to run API tests in CI without needing additional testing frameworks!
Using newman on CircleCI
Use the official orb from: postman/newman
Your config file might look something like this:
version: '2.1'
orbs:
newman: postman/newman@1.0.0
jobs:
newman-collection-run:
executor: newman/postman-newman-docker
steps:
- checkout
- newman/newman-run:
collection: ./cuttlesoftcom.postman_collection.json
environment: ./cuttlesoftcom.postman_environment.jsonUsing newman on GitHub Actions
There’s an unofficial action written by GitHub user @matt-ball that let’s us setup a job to use newman with local files:
name: Run API Tests
on:
pull_request:
branches:
- main
jobs:
newman:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@master
- uses: matt-ball/newman-action@master
with:
collection: cuttlesoftcom.postman_collection.json
environment: cuttlesoftcom.postman_environment.json- Tools
- Postman
