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

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});