At Hyperswitch, we are building an open source payment orchestration solution and the last thing we want to spend time on is trying to identify postman collection diffs manually while reviewing pull requests. The root cause of this challenge is the current collection format. We've come up with a new file format for maintaining postman collections. Let's jump right in!
Postman collections are created using the Postman UI application. These collections are represented as a JSON file by the Postman UI application. It is a single file that contains all the requests/tests/variables etc of the collection. It is designed to be edited within the Postman UI. The newman tool allows teams to run Postman collections as part of their CI pipelines by supplying the Postman collection file as an argument. Typically, teams that rely on Postman for their API testing in CI pipelines maintain a copy of the collection file in their source repository. When teams maintain the Postman collection in their repository, they will have the following workflow to make changes to it and push it upstream:
- Import the collection json file from the repo into Postman UI
- Make changes to the collection in Postman UI
- Export the collection to a file using Postman UI
- Commit and push the changes
There are a few challenges with the above workflow:
1. Collection file diffs are very hard to review in pull requests
- New format collection diff: https://github.com/juspay/hyperswitch/pull/2117/files
2. Developers cannot use their favourite editor to make changes, add/remove new tests.
As a consequence of the above, collection maintenance suffers and often become stale.
Solution to the above challenges
The core reason for challenges presented above is the file format in which the Postman requests are maintained. A single JSON file that encapsulates the entire request code and sequencing does not lend itself for easy reviewing and be an all-editor friendly format.
This fork of newman attempts to address the challenge by representing the Postman collection as a set of directories/files. It allows developers to create Postman collection using the directory representation and also run them. It achieves this by re-constructing the collection json from the directory/file structure and leveraging the existing newman run implementation.
Directory representation of collection
The following is a tree structure of the directory that represents the Postman collection with annotations of what each file corresponds to in a Postman collection.
This concept of representing Postman collections as a directory opens up programmatic pre-processing of request data before running the requests. This could include things like the following:
- Re-using same data across requests
The instructions for using the tool are given below. Please give it spin and let me know it you if it is useful.
Installing newman from this fork
One can install the newman executable in this fork using the command:
npm install -g 'git+ssh://firstname.lastname@example.org:knutties/newman.git#feature/newman-dir'
The following no-arg run shows the new commands added to newman to help manage Postman requests maintained as directories/files instead of a single json file.
The following sections show the invocation of the different commands added in this fork of newman.
Create a new directory based Postman collection
newman dir-collection-create new-dir-collection
Generating directory representation for an existing collection
newman dir-export examples/sample-collection.json
Convert a directory representation back to a Postman collection json file
newman dir-import examples/Sample\ Postman\ Collection/ -o examples/sample-collection.json
Diff the collection generated by export followed by its import
This command is typically used to test the tool itself to ensure it can handle all collection json use-cases.
newman dir-export-import-check examples/sample-collection.json
Execute a Postman collection stored in the directory format
newman dir-run examples/Sample\ Postman\ Collection
The dir-run command supports all the options that the stock run command of newman supports. This is achieved by re-using the same set of command options for both the commands.
Sample output of dir-run shown below
Add a folder under a existing directory
newman dir-add-folder examples/Sample\ Postman\ Collection/folder1
Add a request under a directory
newman dir-add-request examples/Sample\ Postman\ Collection/test4
This command adds the request to the end of the requests already present in the folder. The order of the requests is stored in a separate file called .meta.json. The order of requests can be changed by re-ordering the requests in this file.
Remove a folder
newman dir-remove-folder examples/Sample\ Postman\ Collection/folder1
Remove a request
newman dir-remove-request examples/Sample\ Postman\ Collection/test4