Skip to content

Latest commit

 

History

History
134 lines (91 loc) · 7.69 KB

CONTRIBUTING.md

File metadata and controls

134 lines (91 loc) · 7.69 KB
Raw

Contributing to Postman Code Generators

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.