Contributing to Postman Code Generators

Getting Started Quick
NPM Command Reference
Repository
General Instructions
Pull request guidelines
Tests
Build Failures
Security guidelines

Getting Started Quick

Instructions on initial setup can be found in the README.

NPM Command Reference

`npm install`

Installs all dependencies listed in the root package.json and all the codegens.

`npm run deepinstall`

Installs all dependencies of all the codegens. This runs the command npm install --production --no-audit in all codegens.

npm run deepinstall dev: Installs all dependencies as well as devDependencies of all codegens.

`npm test`

The script associated with npm test will run all tests that ensures that your commit does not break anything in the repository. Additional requirements to run these tests have been listed down in ADDITIONAL_DEPENDENCIES

npm test: Runs structure, unit, newman and system tests for all codegens
npm run test <codegen-name>: Runs tests for a particular codegen.

`npm run boilerplate <codegen-name>`

The command will add a new boilerplate code generator with the name with basic functions and tests, along with the right package.json structure. The format of the codegen name preferably should be language-variant. Please refer the README document.

`npm run cirequirements`

The script associated with this command installs all the additional dependencies that are required to run the generated code snippet on travis. These are important to run the newman tests on travis.

Repository

Directory	Summary
`codegens`	Contains modules for individual language/framework code generators
`lib`	Contains code needed to orchestrate conversion with individual code generation modules. This is the part that the Postman app interfaces with.
`npm`	All CI/build/installation scripts (triggered by NPM run-script)
`test`	Contains test-scripts
`test/codegen`	Runs functional tests on the individual generation modules
`test/system`	Checks for proper code structuring and division across the code generators

Codegen

Every codegen has the following structure.

Directory/File	Summary
`lib`	Contains code needed to convert a Postman SDK request to code snippet.
`npm`	All CI/build/installation scripts (triggered by NPM run-script)
`test`	Contains unit and newman tests.
`test/newman`	Runs newman tests
`test/unit`	Runs unit tests
`index.js`	Exposes two functions: convert and getOptions

General Instructions

Types of contributions

One of the following two contributions are possible for postman-code-generators:

New Code Generator: To add a new code generator, create a pull request to the develop branch of postman-code-generators. Since these code-generators are bundled with the app, they follow a particular structure as mentioned above. We have created a boilerplate for you to get started quickly. Simple run:

$ npm run boilerplate <<codegen-name>>

Bug fixes to existing codegens: We'd be happy to accept fixes to known issues in any of the code-generators, as long it's a filed issue on the issue tracker.

Pull request guidelines

All pull requests should be to the develop branch.
Every pull request should have associated issue(s) on our issue tracker.
For any non-trivial fixes, regression tests should be added as well. For a bug, we also recommend adding a request to the testCollection.json found inside test/codegen/newman/fixtures to run the request using common newman tests.
For a new language to be added as a part of postman-code-generators, we will need some level of community support before we are able to accept the pull request. Feel free to add links to any sort of report/statistics from trusted sources that might help us understand the relevance and popularity of this language among users.

Tests

The CI pipeline on travis will check for code structure across all code generators, and runs functional tests.

Newman Test

Newman tests run a set of fixed collections in Newman, and run each request through the corresponding code generator, and execute it through the relevant interpreter. The responses from Newman and the language interpreter are compared. Currently, there are a set of 3 collections, basicCollection - has a set of some basic requests that every codegen running newman tests has to run, formdataCollection - has requests relating to form-data mode of data transfer and redirectCollection - has requests with follow redirects enabled. Apart from basicCollection all other collections may be skipped for running newman tests with valid reasons.

This mechanism is present in test/codegen/newman. All you need to run these tests is to call the following function:

var runNewmanTest = require(PATH_TO_NEWMAN_UTIL_FOLDER).runNewmanTest;

runNewmanTest(conver, options, testConfig);

convert - The convert function of the codegen to be tested
options - Options object to generate appropriate code snippet
testConfig - These are the test configuration required to compile and run the code snippet.

Example for Java Okhttp:

var convert = require('../../index').convert,
  options = {
    includeBoilerplate: true
  },
  testConfig = {
    fileName: 'main.java', // The file in which the code snippet has to be saved to later compile and run
    compileScript: 'javac -cp *: main.java', // The script required to compile generated code snippet.
    runScript: 'java -cp *: main', // The script required to run the generated code snippet.
    skipCollections: [] // Collections that need to be skipped for testing for a particular codegen.
    // The collection through which newman tests are run will be found inside the `test/codegen/newman/fixtures`. 
  }

For some languages, it's not practical to run an interpreter for generated code. The JS-jQuery is an example. In such cases, the output of the conversion is compared against a known snippet that we know works correctly.

Build Failures

Some common reasons for travis build failures:

If you've added a new code generator, you might have to add some dependencies in npm/ci-requirements for running the code snippet on travis. We use the xenial build of travis. If appropriate dependencies are not added, the newman tests for the codegen will fail.
Use of sudo before bash commands. This is enforced by travis and not adding this will throw error.

Security guidelines

If you've found a vulnerability, or want additional information regarding how we manage security, please send an email to security@getpostman.com. We will review it and respond to you within 24 hours. Please use our PGP public key to encrypt your communications with us.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!