• Stars
    star
    238
  • Rank 169,306 (Top 4 %)
  • Language
    JavaScript
  • License
    Apache License 2.0
  • Created over 8 years ago
  • Updated about 2 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Postman Runtime CI codecov

This is a low-level library used as the backbone for all Collection running & Request sending functionality, in the Postman App, and allied systems (Postman Monitoring, Newman)

If you are looking to execute collections, you should be using Newman, this is very low level.

Options

Postman Runtime supports a lot of options to customize its behavior for different environments and use-cases.

var runner = new runtime.Runner(); // runtime = require('postman-runtime');

// a collection object constructed using the Postman Collection SDK.
var collection = new sdk.Collection();

runner.run(collection, {
    // Iteration Data
    data: [],

    // Timeouts (in ms)
    timeout: {
        request: 30000,
        script: 5000
    },

    // Number of iterations
    iterationCount: 1,

    // Control flags (you can only specify one of these):

    // - gracefully halts on errors (errors in request scripts or while sending the request)
    //   calls the `item` and `iteration` callbacks and does not run any further items (requests)
    stopOnError: true,

    // - abruptly halts the run on errors, and directly calls the `done` callback
    abortOnError: true,

    // - gracefully halts on errors _or_ test failures.
    //   calls the `item` and `iteration` callbacks and does not run any further items (requests)
    stopOnFailure: true,

    // - abruptly halts the run on errors or test failures, and directly calls the `done` callback
    abortOnFailure: true,

    // Environment (a "VariableScope" from the SDK)
    environment: new sdk.VariableScope(),

    // Globals (a "VariableScope" from the SDK)
    globals: new sdk.VariableScope(),

    // Execute a folder/request using id/name or path
    entrypoint: {
        // execute a folder/request using id or name
        execute: 'folderName',
        // idOrName in case of execute and path in case of path
        // is chosen to specify the folder/request to be executed
        lookupStrategy: 'path',
        // execute a folder/request using a path
        path: ['grand_parent_folder_idOrName', 'parent_folder_idOrName']
    },

    // Configure delays (in ms)
    delay: {
        // between each request
        item: 1000,
        // between iterations
        iteration: 1000
    },

    // Used to fetch contents of files, certificates wherever needed
    fileResolver: require('fs'),

    // Options specific to the requester
    requester: {

        // An object compatible with the cookieJar provided by the 'postman-request' module.
        // To limit programmatic cookie access to only whitelisted domains, add `allowProgrammaticAccess`
        // method to the jar. Example:
        // jar.allowProgrammaticAccess = function (domain) { return domain === 'postman-echo.com'; };
        cookieJar: jar,

        // Controls redirect behavior (only supported on Node, ignored in the browser)
        followRedirects: true,

        // Redirect with the original HTTP method (only supported on Node, ignored in the browser)
        followOriginalHttpMethod: false,

        // Maximum number of redirects to follow (only supported on Node, ignored in the browser)
        maxRedirects: 10,

        // Maximum allowed response size in bytes (only supported on Node, ignored in the browser)
        maxResponseSize: 1000000,

        // Enable to use WHATWG URL parser and encoder
        useWhatWGUrlParser: true,

        // Removes the `referer` header when a redirect happens (only supported on Node, ignored in the browser)
        removeRefererHeaderOnRedirect: false,

        // Enable or disable certificate verification (only supported on Node, ignored in the browser)
        strictSSL: false,

        // Use an insecure HTTP parser that accepts invalid HTTP headers (only supported on Node, ignored in the browser)
        insecureHTTPParser: false,

        // Enable or disable detailed request-response timings (only supported on Node, ignored in the browser)
        timings: true,

        // Enable or disable verbose level history (only supported on Node, ignored in the browser)
        verbose: false,

        // Implicitly add `Cache-Control` system header in request (only supported on Node, ignored in the browser)
        implicitCacheControl: true,

        // Implicitly add `Postman-Token` system header in request (only supported on Node, ignored in the browser)
        implicitTraceHeader: true,

        // Add system headers to all requests which cannot be overridden or disabled
        systemHeaders: { 'User-Agent': 'PostmanRuntime' }

        // Extend well known "root" CAs with the extra certificates in file. The file should consist of one or more trusted certificates in PEM format. (only supported on Node, ignored in the browser)
        extendedRootCA: 'path/to/extra/CA/certs.pem',

        // network related options
        network: {
            hostLookup: { // hosts file configuration for dns lookup
                type: 'hostIpMap',
                hostIpMap: {
                    'domain.com': '127.0.0.1',
                    'ipv6-domain.com': '::1',
                }
            },
            restrictedAddresses: {'192.168.1.1': true} // Allows restricting IP/host in requests
        },

        // Custom requesting agents (only supported on Node, ignored in the browser)
        agents: {
            http: {
                agentClass: http.Agent,
                agentOptions: { keepAlive: true, timeout: 399 }
            },
            https: new https.Agent({ keepAlive: true })
        },

        // authorizer related options
        authorizer: {
            // helper to refresh oauth2 tokens during execution
            refreshOAuth2Token: function (id, callback) {
                // calls the callback with the refreshed token or an error
                // callback(err, token)
            },
        }
    },

    // Options specific to the script execution
    script: {

        // Option to set whether to send console logs in serialized format which can be parsed
        // using the `teleport-javascript` serialization library.
        serializeLogs: false
    },

    // A ProxyConfigList, from the SDK
    proxies: new sdk.ProxyConfigList(),

    // A function that fetches the system proxy for a given URL.
    systemProxy: function (url, callback) { return callback(null, {/* ProxyConfig object */}) },

    // Opt-out of [proxy configured using environment variables]((https://github.com/postmanlabs/postman-request#controlling-proxy-behaviour-using-environment-variables) ) (only supported on Node, ignored in the browser)
    ignoreProxyEnvironmentVariables: false,

    // A CertificateList from the SDK
    certificates: new sdk.CertificateList(),

    // *note* Not implemented yet.
    // In the future, this will be used to read certificates from the OS keychain.
    systemCertificate: function() {}
}, function (err, run) {
    console.log('Created a new Run!');

    // Check the section below for detailed documentation on what callbacks should be.
    run.start(callbacks);
});

Callbacks

You can pass a series of callbacks for runtime to execute as a collection is being executed.

runner.run(collection, { /* options */ }, function(err, run) {
    run.start({
        // Called any time we see a new assertion in the test scripts
        assertion: function (cursor, assertions) {
            // cursor = {
            //     position: Number,
            //     iteration: Number,
            //     length: Number,
            //     cycles: Number,
            //     eof: Boolean,
            //     empty: Boolean,
            //     bof: Boolean,
            //     cr: Boolean,
            //     ref: String,
            //     scriptId: String,
            //     eventId: String
            // }

            // assertions: array of assertion objects
            // assertion: {
            //     error: Error,
            //     index: Number,
            //     name: String,
            //     skipped: Number,
            //     passed: Number
            // }
        },

        // Called when the run begins
        start: function (err, cursor) {
            // err: null or Error
            // cursor = {
            //     position: Number,
            //     iteration: Number,
            //     length: Number,
            //     cycles: Number,
            //     eof: Boolean,
            //     empty: Boolean,
            //     bof: Boolean,
            //     cr: Boolean,
            //     ref: String
            // }
        },

        // Called before starting a new iteration
        beforeIteration: function (err, cursor) {
            /* Same as arguments for "start" */
        },

        // Called when an iteration is completed
        iteration: function (err, cursor) {
            /* Same as arguments for "start" */
        },

        // Called before running a new Item (check the postman collection v2 format for what Item means)
        beforeItem: function (err, cursor, item) {
            // err, cursor: Same as arguments for "start"
            // item: sdk.Item
        },

        // Called after completion of an Item
        item: function (err, cursor, item, visualizer) {
            // err, cursor, item: Same as arguments for "beforeItem"

            // visualizer: null or object containing visualizer result that looks like this:
            //  {
            //      -- Tmeplate processing error
            //      error: <Error>
            //
            //      -- Data used for template processing
            //      data: <Object>
            //
            //      -- Processed template
            //      processedTemplate: <String>
            //  }
        },

        // Called before running pre-request script(s) (Yes, Runtime supports multiple pre-request scripts!)
        beforePrerequest: function (err, cursor, events, item) {
            // err, cursor: Same as arguments for "start"
            // events: Array of sdk.Event objects
            // item: sdk.Item
        },

        // Called after running pre-request script(s)
        prerequest: function (err, cursor, results, item) {
            // err, cursor: Same as arguments for "start"
            // item: sdk.Item

            // results: Array of objects. Each object looks like this:
            //  {
            //      error: Error,
            //      event: sdk.Event,
            //      script: sdk.Script,
            //      result: {
            //          target: 'prerequest'
            //
            //          -- Updated environment
            //          environment: <VariableScope>
            //
            //          -- Updated globals
            //          globals: <VariableScope>
            //
            //          data: <Object of data variables>
            //          return: <Object, contains set next request params, etc>
            //      }
            //  }
        },

        // Called before running test script(s)
        beforeTest: function (err, cursor, events, item) {
            // err, cursor: Same as arguments for "start"
            // events: Array of sdk.Event objects
            // item: sdk.Item
        },

        // Called just after running test script (s)
        test: function (err, cursor, results, item) {
            // results: Array of objects. Each object looks like this:
            //  {
            //      error: Error,
            //      event: sdk.Event,
            //      script: sdk.Script,
            //      result: {
            //          target: 'test'
            //
            //          -- Updated environment
            //          environment: <VariableScope>
            //
            //          -- Updated globals
            //          globals: <VariableScope>
            //
            //          response: <sdk.Response>
            //          request: <sdk.Request>
            //          data: <Object of data variables>
            //          cookies: <Array of "sdk.Cookie" objects>
            //          tests: <Object>
            //          return: <Object, contains set next request params, etc>
            //      }
            //  }
        },

        // Called just before sending a request
        beforeRequest: function (err, cursor, request, item) {
            // err, cursor: Same as arguments for "start"
            // item: sdk.Item

            // request: sdk.request
        },

        // Called just after sending a request, may include request replays
        request: function (err, cursor, response, request, item, cookies, history) {
            // err, cursor: Same as arguments for "start"
            // item: sdk.Item

            // response: sdk.Response
            // request: sdk.request
        },

        // Called just after receiving the request-response without waiting for
        // the response body or, request to end.
        // Called once with response for each request in a collection
        responseStart: function (err, cursor, response, request, item, cookies, history) {
            // err, cursor: Same as arguments for "start"
            // item: sdk.Item

            // response: sdk.Response
            // request: sdk.request
        },

        // Called every time a complete server-sent event is received
        responseData: function (cursor, data) {
            // cursor - Same as arguments for "start"
            // data - Event buffer.
        },

        // Called once with response for each request in a collection
        response: function (err, cursor, response, request, item, cookies, history) {
            // err, cursor: Same as arguments for "start"
            // item: sdk.Item

            // response: sdk.Response
            // request: sdk.request
        },

        exception: function (cursor, err) {
             // Called when an exception occurs
             // @param {Object} cursor - A representation of the current run state.
             // @param {Error} err - An Error instance with name, message, and type properties.
        },

        // Called at the end of a run
        done: function (err) {
            // err: null or Error
            console.log('done');
        },

        // Called any time a console.* function is called in test/pre-request scripts
        console: function (cursor, level, ...logs) {},

        io: function (err, cursor, trace, ...otherArgs) {
            // err, cursor: Same as arguments for "start"
            // trace: An object which looks like this:
            // {
            //     -- Indicates the type of IO event, may be HTTP, File, etc. Any requests sent out as a part of
            //     -- auth flows, replays, etc will show up here.
            //     type: 'http',
            //
            //     -- Indicates what this IO event originated from, (collection, auth flows, etc)
            //     source: 'collection'
            // }
            // otherArgs: Variable number of arguments, specific to the type of the IO event.

            // For http type, the otherArgs are:
            // response: sdk.Response()
            // request: sdk.Request()
            // cookies: Array of sdk.Cookie()
        }
    });
});

More Repositories

1

httpbin

HTTP Request & Response Service, written in Python + Flask.
Python
12,664
star
2

newman

Newman is a command-line collection runner for Postman
JavaScript
6,859
star
3

postman-app-support

Postman is an API platform for building and using APIs. Postman simplifies each step of the API lifecycle and streamlines collaboration so you can create better APIs—faster.
5,826
star
4

postman-code-generators

Common repository for all code generators shipped with Postman
JavaScript
991
star
5

openapi-to-postman

Plugin for converting OpenAPI 3.0 specs to the Postman Collection (v2) format
JavaScript
918
star
6

postman-docs

Documentation for Postman, a collaboration platform for API development. Available for Mac, Windows, and Linux.
JavaScript
559
star
7

postman-collection

Javascript module that allows a developer to work with Postman Collections
JavaScript
456
star
8

postman-chrome-interceptor

Helper extension for the Postman packaged app. Also helps send restricted headers.
JavaScript
207
star
9

covid-19-apis

Postman COVID-19 API Resource Center—API collections to help in the COVID-19 fight.
JavaScript
127
star
10

npm-cli-login

JavaScript
113
star
11

swagger2-to-postman

Converter for swagger 2.0 JSON to Postman Collection
JavaScript
113
star
12

postman-sandbox

Sandbox for Postman Scripts to run in Node.js or browser
JavaScript
104
star
13

postman-chrome-extension-legacy

Postman REST Client Chrome Extension (Legacy Version)
JavaScript
94
star
14

postman-collection-transformer

Perform rapid conversion and validation of JSON structure between Postman Collection Format v1 and v2.
JavaScript
87
star
15

postman-flows

We're maintaining this repo to share the progress of Flows publicly and get feedback at the same time.
86
star
16

newman-docker

Docker images for Newman Collection Runner
Shell
80
star
17

swagger2-postman2

Module and library to convert Swagger 2.0 to a Postman Collection (v2.0)
JavaScript
79
star
18

newman-reporter-html

HTML
76
star
19

curl-to-postman

Converts curl requests to Postman Collection v2 request objects
JavaScript
62
star
20

sails-mysql-transactions

sails/waterline ORM with mySQL transaction support
JavaScript
58
star
21

uvm

Universal Virtual Machine for Node and Browser
JavaScript
40
star
22

schemas

Repository of all schemas for JSON structures compatible with Postman (such as the Postman Collection Format)
JavaScript
38
star
23

postman-updater-linux

A simple bash script to update Postman from the command line (for Linux)
Shell
35
star
24

graphql-to-postman

Plugin for converting GraphQL to the Postman Collection (v2) format
JavaScript
34
star
25

gsoc

Postman - Google Summer of Code
32
star
26

node-doc-kube

🐱 URL shortener using cat verbs, cat adjectives, and cat emojis
JavaScript
31
star
27

chai-postman

Chai plugin to assert on Postman Collections
JavaScript
28
star
28

postman-collection-code-generators

Repository for generating code from Postman Collection
JavaScript
22
star
29

postman

21
star
30

e-commerce-store-express

JavaScript
20
star
31

newman-dashboard

A WebUI companion for Newman to control, view and debug runs. 🚀✨
JavaScript
18
star
32

raml2postman

Coverts RAML specs to Postman Collections (v1 of the collection format)
JavaScript
18
star
33

postman-url-encoder

Implements URL encoding according to the WHATWG specification
JavaScript
18
star
34

runscope-to-postman

Convert Runscope Radar Tests to Postman Collection v2
JavaScript
14
star
35

postman-jsdoc-theme

A JSDoc Theme
JavaScript
13
star
36

wsdl-to-postman

Enables Postman support of the WSDL specification
JavaScript
13
star
37

uniscope

Evaluate a code within a controlled environment
JavaScript
12
star
38

env-lift

Simple namespaced environment variable configuration management solution
JavaScript
12
star
39

templates

11
star
40

spectral-postman

A sample API that retrieves constellations as an example to demonstrate features in the OpenAPI 3.0 specification.
Shell
11
star
41

devrel-content

Project to track content creation requests and progress for the Postman Developer Relations team.
10
star
42

api-spec-converter

JavaScript
10
star
43

raml1-to-postman

Converter for RAML1.0 specs to Postman v2 collections
JavaScript
10
star
44

http-reasons

Database to lookup http reasons from http response status code
JavaScript
9
star
45

generic-bitmask

Module to compute and manipulate bitmasks in JavaScript
JavaScript
9
star
46

postman-zendesk-support-theme

Zendesk v2 API theme support for Postman Support Center
Handlebars
8
star
47

letsencrypt-manager

JavaScript
7
star
48

swagger2-postman2-lambda

JavaScript
7
star
49

postmanlabs.github.io

Content for the laboratory website!
HTML
7
star
50

open-technologies-docs

Open Technology Documentation
JavaScript
6
star
51

postman-blog

JavaScript
6
star
52

intergalactic-apifirst

6
star
53

newman-reporter-remote

JavaScript
6
star
54

labs-docs

JavaScript
6
star
55

sails-hook-rewire

Installable sailsjs hook that lets you rewire sails components during tests
JavaScript
5
star
56

codegen-curl

curl snippet generator for Postman Requests
JavaScript
5
star
57

liquid-json

Implementation of JSON that ignores BOM and thows friendly error
JavaScript
5
star
58

uptime-monitors

5
star
59

galaxy-workshop

Supporting resources for the 2020 Postman Galaxy Tour
5
star
60

dhc-to-postman

Converts a DHC Project to a Postman Collection (v1)
JavaScript
5
star
61

postman-badge-checker

Used for checking and awarding Postman badges
5
star
62

node-oauth1

An implementation of OAuth1 signature generation
JavaScript
4
star
63

postman-api-environments-utils

Utilities to manage Postman environments using the Postman API.
JavaScript
4
star
64

postman-japanese-ea

Issue tracking for the Postman App Japanese Early Access release
4
star
65

serialised-error

Serialises error object to normal object
JavaScript
4
star
66

swagger1-to-postman

JavaScript
3
star
67

schema-compiler

json-schema-builder
JavaScript
3
star
68

sails-hook-responders

An installable sailsjs hook that adds policies, called responders, to a request
JavaScript
3
star
69

postman-validator

JavaScript
3
star
70

.github

3
star
71

learning-resources

3
star
72

postman-sdk-go

Go SDK powering Live Collections
Go
3
star
73

execute-postman-monitor

GitHub action that executes a Postman Monitor.
JavaScript
3
star
74

newman-orb

CircleCI Orb for running collections with Newman - https://circleci.com/orbs/registry/orb/postman/newman
3
star
75

async-domino

A module to allow time guaranteed asynchronous functions
JavaScript
3
star
76

har-to-postman

JavaScript
3
star
77

save-as-postman-request

Command line utility to process piped curl responses and create postman a request on a collection using the Postman API
JavaScript
3
star
78

solutions

Useful learning resources, scripts, videos, snippets and materials etc. collated by the Solutions Engineering team at Postman.
2
star
79

postman-learning

Postman and API Development
2
star
80

gists

2
star
81

examples

2
star
82

intergalactic-ice-cream

2
star
83

ical-json

JSON representation of calendar entries (with cron compatibility)
JavaScript
2
star
84

mime-format

Database to mime-format based on content-type header and content
JavaScript
2
star
85

pratishat

Percent-encode specific characters in the string
JavaScript
2
star
86

push-openapi-to-postman

Github action that pushes an OpenAPI in the repository to a specific API in a Postman workspace, creating a new version.
JavaScript
2
star
87

sails-env-switch

JavaScript
2
star
88

postman-mock-servers

1
star
89

raml-to-postman

RAML
1
star
90

packity

Sanity check of installed packages as per package.json
JavaScript
1
star
91

livestream-content

Content used and shared on Livestream events
Python
1
star
92

eslint-config-postman

Common ESLint rules for Postman! 👕
JavaScript
1
star
93

orbit-actions

1
star
94

collection-format-docs

Documentation for postman collection format, the open source specification that powers collections in postman
JavaScript
1
star
95

postman-collection-spectral-linter

Utility to lint and validate the quality of a Postman collection
JavaScript
1
star