Postman Runtime

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.

1var runner = new runtime.Runner(); // runtime = require('postman-runtime');
2
3// a collection object constructed using the Postman Collection SDK.
4var collection = new sdk.Collection();
5
6runner.run(collection, {
7    // Iteration Data
8    data: [],
9
10    // Timeouts (in ms)
11    timeout: {
12        request: 30000,
13        script: 5000
14    },
15
16    // Number of iterations
17    iterationCount: 1,
18
19    // Control flags (you can only specify one of these):
20
21    // - gracefully halts on errors (errors in request scripts or while sending the request)
22    //   calls the `item` and `iteration` callbacks and does not run any further items (requests)
23    stopOnError: true,
24
25    // - abruptly halts the run on errors, and directly calls the `done` callback
26    abortOnError: true,
27
28    // - gracefully halts on errors _or_ test failures.
29    //   calls the `item` and `iteration` callbacks and does not run any further items (requests)
30    stopOnFailure: true,
31
32    // - abruptly halts the run on errors or test failures, and directly calls the `done` callback
33    abortOnFailure: true,
34
35    // Environment (a "VariableScope" from the SDK)
36    environment: new sdk.VariableScope(),
37
38    // Globals (a "VariableScope" from the SDK)
39    globals: new sdk.VariableScope(),
40
41    // Local variables (a "VariableScope" from the SDK)
42    localVariables: new sdk.VariableScope(),
43
44    // Execute a folder/request using id/name or path
45    entrypoint: {
46        // execute a folder/request using id or name
47        execute: 'folderName',
48        // idOrName in case of execute and path in case of path
49        // is chosen to specify the folder/request to be executed
50        lookupStrategy: 'path',
51        // execute a folder/request using a path
52        path: ['grand_parent_folder_idOrName', 'parent_folder_idOrName']
53    },
54
55    // Configure delays (in ms)
56    delay: {
57        // between each request
58        item: 1000,
59        // between iterations
60        iteration: 1000
61    },
62
63    // Used to fetch contents of files, certificates wherever needed
64    fileResolver: require('fs'),
65
66    // Options specific to the requester
67    requester: {
68
69        // An object compatible with the cookieJar provided by the 'postman-request' module.
70        // To limit programmatic cookie access to only whitelisted domains, add `allowProgrammaticAccess`
71        // method to the jar. Example:
72        // jar.allowProgrammaticAccess = function (domain) { return domain === 'postman-echo.com'; };
73        cookieJar: jar,
74
75        // Controls redirect behavior (only supported on Node, ignored in the browser)
76        followRedirects: true,
77
78        // Redirect with the original HTTP method (only supported on Node, ignored in the browser)
79        followOriginalHttpMethod: false,
80
81        // Maximum number of redirects to follow (only supported on Node, ignored in the browser)
82        maxRedirects: 10,
83
84        // Maximum allowed response size in bytes (only supported on Node, ignored in the browser)
85        maxResponseSize: 1000000,
86
87        // HTTP Protocol version to use. Valid options are http1, http2, and auto (only supported on Node, ignored in the browser)
88        protocolVersion: 'http1',
89
90        // Enable to use WHATWG URL parser and encoder
91        useWhatWGUrlParser: true,
92
93        // Removes the `referer` header when a redirect happens (only supported on Node, ignored in the browser)
94        removeRefererHeaderOnRedirect: false,
95
96        // Enable or disable certificate verification (only supported on Node, ignored in the browser)
97        strictSSL: false,
98
99        // Use an insecure HTTP parser that accepts invalid HTTP headers (only supported on Node, ignored in the browser)
100        insecureHTTPParser: false,
101
102        // Enable or disable detailed request-response timings (only supported on Node, ignored in the browser)
103        timings: true,
104
105        // Enable or disable verbose level history (only supported on Node, ignored in the browser)
106        verbose: false,
107
108        // Implicitly add `Cache-Control` system header in request (only supported on Node, ignored in the browser)
109        implicitCacheControl: true,
110
111        // Implicitly add `Postman-Token` system header in request (only supported on Node, ignored in the browser)
112        implicitTraceHeader: true,
113
114        // Add system headers to all requests which cannot be overridden or disabled
115        systemHeaders: { 'User-Agent': 'PostmanRuntime' }
116
117        // 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)
118        extendedRootCA: 'path/to/extra/CA/certs.pem',
119
120        // network related options
121        network: {
122            hostLookup: { // hosts file configuration for dns lookup
123                type: 'hostIpMap',
124                hostIpMap: {
125                    'domain.com': '127.0.0.1',
126                    'ipv6-domain.com': '::1',
127                }
128            },
129            restrictedAddresses: {'192.168.1.1': true} // Allows restricting IP/host in requests
130        },
131
132        // Custom requesting agents (only supported on Node, ignored in the browser)
133        agents: {
134            http: {
135                agentClass: http.Agent,
136                agentOptions: { keepAlive: true, timeout: 399 }
137            },
138            https: new https.Agent({ keepAlive: true })
139        },
140
141        // authorizer related options
142        authorizer: {
143            // helper to refresh oauth2 tokens during execution
144            refreshOAuth2Token: function (id, callback) {
145                // calls the callback with the refreshed token or an error
146                // callback(err, token)
147            },
148        }
149    },
150
151    // Options specific to the script execution
152    script: {
153
154        // Option to set whether to send console logs in serialized format which can be parsed
155        // using the `teleport-javascript` serialization library.
156        serializeLogs: false,
157
158        // Function to resolve packages that are used in the script.
159        packageResolver: function ({ packages /* sdk.Script.packages */ }, callback) {
160            return callback(null, {
161                pkg1: {
162                    data: 'packagedata'
163                },
164                pkg2: {
165                    error: 'Failed to get package'
166                }
167            });
168        }
169    },
170
171    // A ProxyConfigList, from the SDK
172    proxies: new sdk.ProxyConfigList(),
173
174    // A function that fetches the system proxy for a given URL.
175    systemProxy: function (url, callback) { return callback(null, {/* ProxyConfig object */}) },
176
177    // 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)
178    ignoreProxyEnvironmentVariables: false,
179
180    // A CertificateList from the SDK
181    certificates: new sdk.CertificateList(),
182
183    // *note* Not implemented yet.
184    // In the future, this will be used to read certificates from the OS keychain.
185    systemCertificate: function() {}
186}, function (err, run) {
187    console.log('Created a new Run!');
188
189    // Check the section below for detailed documentation on what callbacks should be.
190    run.start(callbacks);
191});

Callbacks

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

1runner.run(collection, { /* options */ }, function(err, run) {
2    run.start({
3        // Called any time we see a new assertion in the test scripts
4        assertion: function (cursor, assertions) {
5            // cursor = {
6            //     position: Number,
7            //     iteration: Number,
8            //     length: Number,
9            //     cycles: Number,
10            //     eof: Boolean,
11            //     empty: Boolean,
12            //     bof: Boolean,
13            //     cr: Boolean,
14            //     ref: String,
15            //     scriptId: String,
16            //     eventId: String
17            // }
18
19            // assertions: array of assertion objects
20            // assertion: {
21            //     error: Error,
22            //     index: Number,
23            //     name: String,
24            //     skipped: Number,
25            //     passed: Number
26            // }
27        },
28
29        // Called when the run begins
30        start: function (err, cursor) {
31            // err: null or Error
32            // cursor = {
33            //     position: Number,
34            //     iteration: Number,
35            //     length: Number,
36            //     cycles: Number,
37            //     eof: Boolean,
38            //     empty: Boolean,
39            //     bof: Boolean,
40            //     cr: Boolean,
41            //     ref: String
42            // }
43        },
44
45        // Called before starting a new iteration
46        beforeIteration: function (err, cursor) {
47            /* Same as arguments for "start" */
48        },
49
50        // Called when an iteration is completed
51        iteration: function (err, cursor) {
52            /* Same as arguments for "start" */
53        },
54
55        // Called before running a new Item (check the postman collection v2 format for what Item means)
56        beforeItem: function (err, cursor, item) {
57            // err, cursor: Same as arguments for "start"
58            // item: sdk.Item
59        },
60
61        // Called after completion of an Item
62        item: function (err, cursor, item, visualizer, result) {
63            // err, cursor, item: Same as arguments for "beforeItem"
64
65            // visualizer: null or object containing visualizer result that looks like this:
66            //  {
67            //      -- Tmeplate processing error
68            //      error: <Error>
69            //
70            //      -- Data used for template processing
71            //      data: <Object>
72            //
73            //      -- Processed template
74            //      processedTemplate: <String>
75            //  }
76
77            // result: undefined or object containing following properties
78            // {
79            //      -- True for items skipped using pm.execution.skipRequest
80            //         isSkipped: <Boolean>
81            // }
82
83        },
84
85        // Called before running pre-request script(s) (Yes, Runtime supports multiple pre-request scripts!)
86        beforePrerequest: function (err, cursor, events, item) {
87            // err, cursor: Same as arguments for "start"
88            // events: Array of sdk.Event objects
89            // item: sdk.Item
90        },
91
92        // Called after running pre-request script(s)
93        prerequest: function (err, cursor, results, item) {
94            // err, cursor: Same as arguments for "start"
95            // item: sdk.Item
96
97            // results: Array of objects. Each object looks like this:
98            //  {
99            //      error: Error,
100            //      event: sdk.Event,
101            //      script: sdk.Script,
102            //      result: {
103            //          target: 'prerequest'
104            //
105            //          -- Updated environment
106            //          environment: <VariableScope>
107            //
108            //          -- Updated globals
109            //          globals: <VariableScope>
110            //
111            //          data: <Object of data variables>
112            //          return: <Object, contains set next request params, etc>
113            //      }
114            //  }
115        },
116
117        // Called before running test script(s)
118        beforeTest: function (err, cursor, events, item) {
119            // err, cursor: Same as arguments for "start"
120            // events: Array of sdk.Event objects
121            // item: sdk.Item
122        },
123
124        // Called just after running test script (s)
125        test: function (err, cursor, results, item) {
126            // results: Array of objects. Each object looks like this:
127            //  {
128            //      error: Error,
129            //      event: sdk.Event,
130            //      script: sdk.Script,
131            //      result: {
132            //          target: 'test'
133            //
134            //          -- Updated environment
135            //          environment: <VariableScope>
136            //
137            //          -- Updated globals
138            //          globals: <VariableScope>
139            //
140            //          response: <sdk.Response>
141            //          request: <sdk.Request>
142            //          data: <Object of data variables>
143            //          cookies: <Array of "sdk.Cookie" objects>
144            //          tests: <Object>
145            //          return: <Object, contains set next request params, etc>
146            //      }
147            //  }
148        },
149
150        // Called just before sending a request
151        beforeRequest: function (err, cursor, request, item) {
152            // err, cursor: Same as arguments for "start"
153            // item: sdk.Item
154
155            // request: sdk.request
156        },
157
158        // Called just after sending a request, may include request replays
159        request: function (err, cursor, response, request, item, cookies, history) {
160            // err, cursor: Same as arguments for "start"
161            // item: sdk.Item
162
163            // response: sdk.Response
164            // request: sdk.request
165        },
166
167        // Called just after receiving the request-response without waiting for
168        // the response body or, request to end.
169        // Called once with response for each request in a collection
170        responseStart: function (err, cursor, response, request, item, cookies, history) {
171            // err, cursor: Same as arguments for "start"
172            // item: sdk.Item
173
174            // response: sdk.Response
175            // request: sdk.request
176        },
177
178        // Called every time a complete server-sent event is received
179        responseData: function (cursor, data) {
180            // cursor - Same as arguments for "start"
181            // data - Event buffer.
182        },
183
184        // Called once with response for each request in a collection
185        response: function (err, cursor, response, request, item, cookies, history) {
186            // err, cursor: Same as arguments for "start"
187            // item: sdk.Item
188
189            // response: sdk.Response
190            // request: sdk.request
191        },
192
193        exception: function (cursor, err) {
194             // Called when an exception occurs
195             // @param {Object} cursor - A representation of the current run state.
196             // @param {Error} err - An Error instance with name, message, and type properties.
197        },
198
199        // Called at the end of a run
200        done: function (err) {
201            // err: null or Error
202            console.log('done');
203        },
204
205        // Called any time a console.* function is called in test/pre-request scripts
206        console: function (cursor, level, ...logs) {},
207
208        io: function (err, cursor, trace, ...otherArgs) {
209            // err, cursor: Same as arguments for "start"
210            // trace: An object which looks like this:
211            // {
212            //     -- Indicates the type of IO event, may be HTTP, File, etc. Any requests sent out as a part of
213            //     -- auth flows, replays, etc will show up here.
214            //     type: 'http',
215            //
216            //     -- Indicates what this IO event originated from, (collection, auth flows, etc)
217            //     source: 'collection'
218            // }
219            // otherArgs: Variable number of arguments, specific to the type of the IO event.
220
221            // For http type, the otherArgs are:
222            // response: sdk.Response()
223            // request: sdk.Request()
224            // cookies: Array of sdk.Cookie()
225        }
226    });
227});