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

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) {
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
78        // Called before running pre-request script(s) (Yes, Runtime supports multiple pre-request scripts!)
79        beforePrerequest: function (err, cursor, events, item) {
80            // err, cursor: Same as arguments for "start"
81            // events: Array of sdk.Event objects
82            // item: sdk.Item
83        },
84
85        // Called after running pre-request script(s)
86        prerequest: function (err, cursor, results, item) {
87            // err, cursor: Same as arguments for "start"
88            // item: sdk.Item
89
90            // results: Array of objects. Each object looks like this:
91            //  {
92            //      error: Error,
93            //      event: sdk.Event,
94            //      script: sdk.Script,
95            //      result: {
96            //          target: 'prerequest'
97            //
98            //          -- Updated environment
99            //          environment: <VariableScope>
100            //
101            //          -- Updated globals
102            //          globals: <VariableScope>
103            //
104            //          data: <Object of data variables>
105            //          return: <Object, contains set next request params, etc>
106            //      }
107            //  }
108        },
109
110        // Called before running test script(s)
111        beforeTest: function (err, cursor, events, item) {
112            // err, cursor: Same as arguments for "start"
113            // events: Array of sdk.Event objects
114            // item: sdk.Item
115        },
116
117        // Called just after running test script (s)
118        test: function (err, cursor, results, item) {
119            // results: Array of objects. Each object looks like this:
120            //  {
121            //      error: Error,
122            //      event: sdk.Event,
123            //      script: sdk.Script,
124            //      result: {
125            //          target: 'test'
126            //
127            //          -- Updated environment
128            //          environment: <VariableScope>
129            //
130            //          -- Updated globals
131            //          globals: <VariableScope>
132            //
133            //          response: <sdk.Response>
134            //          request: <sdk.Request>
135            //          data: <Object of data variables>
136            //          cookies: <Array of "sdk.Cookie" objects>
137            //          tests: <Object>
138            //          return: <Object, contains set next request params, etc>
139            //      }
140            //  }
141        },
142
143        // Called just before sending a request
144        beforeRequest: function (err, cursor, request, item) {
145            // err, cursor: Same as arguments for "start"
146            // item: sdk.Item
147
148            // request: sdk.request
149        },
150
151        // Called just after sending a request, may include request replays
152        request: function (err, cursor, response, request, item, cookies, history) {
153            // err, cursor: Same as arguments for "start"
154            // item: sdk.Item
155
156            // response: sdk.Response
157            // request: sdk.request
158        },
159
160        // Called just after receiving the request-response without waiting for
161        // the response body or, request to end.
162        // Called once with response for each request in a collection
163        responseStart: function (err, cursor, response, request, item, cookies, history) {
164            // err, cursor: Same as arguments for "start"
165            // item: sdk.Item
166
167            // response: sdk.Response
168            // request: sdk.request
169        },
170
171        // Called every time a complete server-sent event is received
172        responseData: function (cursor, data) {
173            // cursor - Same as arguments for "start"
174            // data - Event buffer.
175        },
176
177        // Called once with response for each request in a collection
178        response: function (err, cursor, response, request, item, cookies, history) {
179            // err, cursor: Same as arguments for "start"
180            // item: sdk.Item
181
182            // response: sdk.Response
183            // request: sdk.request
184        },
185
186        exception: function (cursor, err) {
187             // Called when an exception occurs
188             // @param {Object} cursor - A representation of the current run state.
189             // @param {Error} err - An Error instance with name, message, and type properties.
190        },
191
192        // Called at the end of a run
193        done: function (err) {
194            // err: null or Error
195            console.log('done');
196        },
197
198        // Called any time a console.* function is called in test/pre-request scripts
199        console: function (cursor, level, ...logs) {},
200
201        io: function (err, cursor, trace, ...otherArgs) {
202            // err, cursor: Same as arguments for "start"
203            // trace: An object which looks like this:
204            // {
205            //     -- Indicates the type of IO event, may be HTTP, File, etc. Any requests sent out as a part of
206            //     -- auth flows, replays, etc will show up here.
207            //     type: 'http',
208            //
209            //     -- Indicates what this IO event originated from, (collection, auth flows, etc)
210            //     source: 'collection'
211            // }
212            // otherArgs: Variable number of arguments, specific to the type of the IO event.
213
214            // For http type, the otherArgs are:
215            // response: sdk.Response()
216            // request: sdk.Request()
217            // cookies: Array of sdk.Cookie()
218        }
219    });
220});