A client to facilitate local development of requests, responses and scripts for Postman.
This functionality should be considered pre-alpha/early access. Use caution around production systems and anticipate breaking changes throughout this period.
Allows for editing of Postman requests, responses and scripts inside your chosen editor. For scripts, this has a few additional benefits:
- Work with JavaScript files instead of the Postman collection JSON structure
- Use of
require
to include local files/libraries from NPM (you mustnpm install
) not otherwise available in Postman's sandbox - Version control your Postman scripts alongside your API code
Note: due to the bundling process involved in including additional libraries, this CLI does not provide a "best of both worlds", where you can edit your scripts in both the Postman app or the IDE. If you'd like to continue to edit scripts in Postman, check out how to use Postman's own version control.
Node version 10.12 or higher is required.
npm i -g @matt.ball/postman-cli
Run postman setup
within the root directory of your project to setup a Postman CLI config.
See the Postman Learning Center for details on creating an API key.
Run the postman
command from the root directory of your repo.
Converts a collections requests, responses and scripts to JSON/JavaScript files, placed in the directory specified during postman setup
. Run this command whenever adding requests, responses or scripts on the Postman side - it will not update previously bootstrapped request, response or script files. It will also create a collection JSON file, and environment files too (if you selected some during postman setup
). See more at bootstrapping.
Creates both collection and environment(s) (if present) in My Workspace
in Postman for testing. Will update pre-existing clones after running once. Useful when checking out others branches or before using postman update
and updating the original resources.
Run for intial setup or later reconfiguration. Generates a .postman.json
configuration file.
Converts the files created with postman bootstrap
back to the Postman collection format (JSON). Use after making changes and before pushing to your VCS, running postman clone
or postman update
.
Updates the original collection and any environment(s) in the Postman app with your local changes. Useful for CI/CD on merge to master - include your config/secrets .postman.json
file (generated from postman setup
) within this environment. Note: scripts in Postman will now include additional code through the Postman CLI bundling process - it's easier to edit locally only at this point.
-
From the root of your repo:
postman bootstrap
-
Edit the files produced by the CLI.
-
Sync the changes back to the Postman collection format:
postman sync
-
Run your changes through Newman locally, or feed the changes back into Postman via:
postman update
Running postman bootstrap
will create a number of files and folders in the directory you chose during postman setup
. This will be reflective of the collection you are bootstrapping.
For example, a collection containing 2 requests named Request A
and Request B
, where A
has a request and a test script defined, and B
has a request, response and pre-request script defined the following following structure would be created:
๐ฆ repo โฃ ๐ postman โ โฃ ๐ Request A โ โ โฃ ๐ request.json โ โ โ ๐ test.js โ โ ๐ Request B โ โฃ ๐ request.json โ โฃ ๐ response.json โ โ ๐ prerequest.js โฃ ๐ postman_collection.json โ ๐ postman_environment.json
Once postman bootstrap
has been run, running the command again will only serve to create new files/folders if new requests, responses or scripts have been made through the Postman app. It will not touch already bootstrapped files. You can add new elements by creating a request.json
, response.json
, test.js
or prerequest.js
file yourself.
Finally, postman bootstrap
will create a collection JSON file for your convenience. This can be kept in sync with changes to files in the postman
directory by running postman sync
. Environment file(s) will also be created if they exist and are optioned during postman setup
. Should you wish to add environments at a later date, run postman setup
again.
-
Open a new branch:
git checkout -b shiny-new-feature
-
Make code changes:
git add src/
git commit -m 'update api code'
-
Update Postman test scripts, sync to Postman collection format:
postman sync
-
Validate tests in personal workspace in Postman:
postman clone
-
Add, commit, push changes:
git add postman/
git add postman_collection.json
git commit -m 'update api tests'
git push
-
PR opens, CI runs Newman:
newman run postman_collection.json -e postman_environment.json
-
PR approved and merged, CD runs the following, updating Postman collection to Postman app:
echo ${{ secrets.postmanCli }} > .postman.json
postman update
Use pm
instead of postman
for extra speed.
Use pm --help
to see all commands.