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        // Maximum allowed header size in bytes (only supported on Node HTTP/1, ignored in the browser and when using HTTP/2)
88        maxHeaderSize: 1000000,
89
90        // HTTP Protocol version to use. Valid options are http1, http2, and auto (only supported on Node, ignored in the browser)
91        protocolVersion: 'http1',
92
93        // Enable to use WHATWG URL parser and encoder
94        useWhatWGUrlParser: true,
95
96        // Removes the `referer` header when a redirect happens (only supported on Node, ignored in the browser)
97        removeRefererHeaderOnRedirect: false,
98
99        // Enable or disable certificate verification (only supported on Node, ignored in the browser)
100        strictSSL: false,
101
102        // Use an insecure HTTP parser that accepts invalid HTTP headers (only supported on Node, ignored in the browser)
103        insecureHTTPParser: false,
104
105        // Enable or disable detailed request-response timings (only supported on Node, ignored in the browser)
106        timings: true,
107
108        // Enable or disable verbose level history (only supported on Node, ignored in the browser)
109        verbose: false,
110
111        // Implicitly add `Cache-Control` system header in request (only supported on Node, ignored in the browser)
112        implicitCacheControl: true,
113
114        // Implicitly add `Postman-Token` system header in request (only supported on Node, ignored in the browser)
115        implicitTraceHeader: true,
116
117        // Add system headers to all requests which cannot be overridden or disabled
118        systemHeaders: { 'User-Agent': 'PostmanRuntime' },
119
120        // 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)
121        extendedRootCA: 'path/to/extra/CA/certs.pem',
122
123        // network related options
124        network: {
125            hostLookup: { // hosts file configuration for dns lookup
126                type: 'hostIpMap',
127                hostIpMap: {
128                    'domain.com': '127.0.0.1',
129                    'ipv6-domain.com': '::1',
130                }
131            },
132            restrictedAddresses: {'192.168.1.1': true} // Allows restricting IP/host in requests
133        },
134
135        // Custom requesting agents (only supported on Node, ignored in the browser)
136        agents: {
137            http: {
138                agentClass: http.Agent,
139                agentOptions: { keepAlive: true, timeout: 399 }
140            },
141            https: new https.Agent({ keepAlive: true })
142        },
143
144        // authorizer related options
145        authorizer: {
146            // helper to refresh oauth2 tokens during execution
147            refreshOAuth2Token: function (id, callback) {
148                // calls the callback with the refreshed token or an error
149                // callback(err, token)
150            },
151        }
152    },
153
154    // Options specific to the script execution
155    script: {
156
157        // Option to set whether to send console logs in serialized format which can be parsed
158        // using the `teleport-javascript` serialization library.
159        serializeLogs: false,
160
161        // Function to resolve packages that are used in the script.
162        packageResolver: function ({ packages /* sdk.Script.packages */ }, callback) {
163            return callback(null, {
164                pkg1: {
165                    data: 'packagedata'
166                },
167                pkg2: {
168                    error: 'Failed to get package'
169                }
170            });
171        }
172    },
173
174    // A ProxyConfigList, from the SDK
175    proxies: new sdk.ProxyConfigList(),
176
177    // A function that fetches the system proxy for a given URL.
178    systemProxy: function (url, callback) { return callback(null, {/* ProxyConfig object */}) },
179
180    // 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)
181    ignoreProxyEnvironmentVariables: false,
182
183    // A CertificateList from the SDK
184    certificates: new sdk.CertificateList(),
185
186    // *note* Not implemented yet.
187    // In the future, this will be used to read certificates from the OS keychain.
188    systemCertificate: function() {}
189}, function (err, run) {
190    console.log('Created a new Run!');
191
192    // Check the section below for detailed documentation on what callbacks should be.
193    run.start(callbacks);
194});

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