From 1548ee62b661200fcb9d439d16c072a66dbfa718 Mon Sep 17 00:00:00 2001 From: Pa1NarK <69745008+pixincreate@users.noreply.github.com> Date: Tue, 17 Oct 2023 20:17:19 +0530 Subject: [PATCH] docs(postman): Rewrite postman documentation to help devs develop tests for their features (#2613) --- crates/test_utils/README.md | 2 ++ postman/README.md | 49 +++++++++++++++++++------------------ 2 files changed, 27 insertions(+), 24 deletions(-) diff --git a/crates/test_utils/README.md b/crates/test_utils/README.md index bfed3479b3..1e92174b33 100644 --- a/crates/test_utils/README.md +++ b/crates/test_utils/README.md @@ -2,6 +2,8 @@ The heart of `newman`(with directory support) and `UI-tests` +> If you're developing a collection and you want to learn more about it, click [_**here**_](/README.md) + ## Newman - Make sure you that you _**do not**_ have the newman (from the Postman team) installed but rather the `newman` fork with directory support diff --git a/postman/README.md b/postman/README.md index bebdb3aaef..342e7ebe1b 100644 --- a/postman/README.md +++ b/postman/README.md @@ -1,34 +1,35 @@ # Postman Collection -You can find the latest Postman collection [here][postman-collection]. -For getting started quickly, you can also -[fork the Postman collection][postman-collection-fork] under your workspace. +This directory contains the Postman collection for all Hyperswitch supported connectors and this documentation talks about how to build the collection. -## Auto-Generating the Postman Collection +## Development of collections -The [Postman collection][postman-collection] is generated using -[`portman`][portman] tool from the [OpenAPI specification][openapi-spec]. -If you'd like to generate the collection from the OpenAPI specification, you can -follow the below steps: +### Prerequisites -1. Install `portman`, refer to the instructions on - [the repository][portman-repository]: +- [Postman](https://www.postman.com/downloads/) +- Newman CLI fork from npm: npm install -g 'https://github.com/knutties/newman.git#feature/newman-dir' - ```shell - npm install -g @apideck/portman - ``` +### Steps to build the collection -2. From the root of the project directory, run the following command to generate - the Postman collection. +- `stripe.postman_collection.json` is the most up-to-date collection that consists of all the features that Hyperswitch supports +- It is recommended that you use the `stripe.postman_collection.json` as the base collection to build the collection for other connectors +- If you developed a new feature, make sure you add them to the `stripe.postman_collection.json` given that it is a core feature. If it is collection specific, add it to the respective collection - ```shell - portman --cliOptionsFile postman/portman-cli.json - ``` +--- -**NOTE:** Please verify Postman collection variables before trying out the APIs. +- The collection consists of many directories and each directory consists of a set of requests. Each directory is a feature and each request is a test case +- The directory name should be the name of the feature and the request name should be the name of the test case +- If the feature that you add is a flow test case, make sure you add the test case to the `Flow Testcases` directory. If you did a refactor that handles errors say, expiry date of a card, make sure you add the test case to the `Variation Cases` directory prefixed by `Scenario-` where `` is the number of the scenario +- If the feature that you add is a core feature, make sure you add the test case to the `Happy Cases` directory where only the happy cases are tested. -[postman-collection]: https://www.postman.com/hyperswitch/workspace/hyperswitch/collection/25176183-e36f8e3d-078c-4067-a273-f456b6b724ed -[postman-collection-fork]: https://www.postman.com/hyperswitch/workspace/hyperswitch/collection/25176183-e36f8e3d-078c-4067-a273-f456b6b724ed/fork -[portman]: https://www.npmjs.com/package/@apideck/portman -[openapi-spec]: /openapi/open_api_spec.yaml -[portman-repository]: https://github.com/apideck-libraries/portman +--- + +- Make sure that you update the `tests` section where the necessary `javascript` code has to written/updated to test the feature (assertion checks where you verify the results obtained with the expected outcome) +- If certain `tests` need to be run at the time of making a request, make sure you add them to the `Pre-request Script` section of the request + +--- + +- After all the development is done, make sure you right click and run the collection in respective environments to make sure that the collection runs successfully +- Export the collection as `v2.1` and save it `postman/collection-json` directory +- Export the postman-collection to its directory structure by using the command `newman dir-export /path/to/collection.json` and move the folder to `postman/collection-dir` (for more info, refer to [Newman-Fork](https://github.com/juspay/hyperswitch/tree/main/crates/test_utils#newman)) +- You can run the dir postman collection from newman using `rustman` by referring [here](https://github.com/juspay/hyperswitch/tree/main/crates/test_utils#running-tests) \ No newline at end of file