diff --git a/docs.json b/docs.json index 59b8018..820ffc8 100644 --- a/docs.json +++ b/docs.json @@ -111,7 +111,9 @@ "general/api-client/rq-api-reference/rq-collection-variables", "general/api-client/rq-api-reference/rq-globals", "general/api-client/rq-api-reference/rq-test", - "general/api-client/rq-api-reference/rq-expect" + "general/api-client/rq-api-reference/rq-expect", + "general/api-client/rq-api-reference/rq-info", + "general/api-client/rq-api-reference/rq-iteration-data" ] }, { diff --git a/general/api-client/collection-runner-data-file.mdx b/general/api-client/collection-runner-data-file.mdx index 2e55f19..d03343c 100644 --- a/general/api-client/collection-runner-data-file.mdx +++ b/general/api-client/collection-runner-data-file.mdx @@ -112,4 +112,27 @@ Austin London ``` -Requestly will automatically replace `{{city}}` with each value during the run. \ No newline at end of file +Requestly will automatically replace `{{city}}` with each value during the run. + +### Accessing Data in Scripts + +You can access data file values programmatically in your pre-request and post-response scripts using the `rq.iterationData` object. This allows you to implement conditional logic, validate responses, or perform calculations based on the input data. + +**Example:** +```javascript +// Pre-request script +const city = rq.iterationData.get("city"); +console.log(`Testing weather API for: ${city}`); + +// Post-response script +const expectedCity = rq.iterationData.get("city"); +const responseData = rq.response.json(); + +rq.test("Response contains correct city", function() { + rq.expect(responseData.city).to.equal(expectedCity); +}); +``` + +Learn more about accessing iteration data in scripts: +- [rq.iterationData API Reference](/general/api-client/rq-api-reference/rq-iteration-data) +- [rq.info API Reference](/general/api-client/rq-api-reference/rq-info) - Access iteration metadata \ No newline at end of file diff --git a/general/api-client/rq-api-reference/rq-info.mdx b/general/api-client/rq-api-reference/rq-info.mdx new file mode 100644 index 0000000..0081c8b --- /dev/null +++ b/general/api-client/rq-api-reference/rq-info.mdx @@ -0,0 +1,143 @@ +--- +title: rq.info +label: rq.info +slug: rq-info +description: Access execution metadata including request name, iteration index, and event name in Requestly API client scripts. +seoDescription: Access execution metadata including request name, iteration index, and event name in Requestly API client scripts. +visibility: PUBLIC +--- + +The `rq.info` object provides metadata about the current script execution context. It contains information about the request being executed, the current iteration (when running collections), and the event type. + +## Properties + +### `rq.info.requestId` + +**Type:** `string` + +The unique identifier of the request being executed. + +**Example:** +```javascript +console.log("Request ID:", rq.info.requestId); +// Output: Request ID: abc123xyz +``` + +--- + +### `rq.info.requestName` + +**Type:** `string` + +The name of the request being executed. + +**Example:** +```javascript +console.log("Executing request:", rq.info.requestName); +// Output: Executing request: Get User Profile +``` + +--- + +### `rq.info.eventName` + +**Type:** `"prerequest" | "postresponse"` + +The type of script event currently executing. Returns `"prerequest"` for pre-request scripts and `"postresponse"` for post-response scripts. + +**Example:** +```javascript +if (rq.info.eventName === "prerequest") { + console.log("Running pre-request script"); +} else { + console.log("Running post-response script"); +} +``` + +--- + +### `rq.info.iteration` + +**Type:** `number` + +The current iteration index when running a collection with the Collection Runner. The index is **0-based**, meaning the first iteration is `0`, the second is `1`, and so on. + +For single request executions (not part of a collection run), this value is `0`. + +**Example:** +```javascript +console.log("Current iteration:", rq.info.iteration); +// Output: Current iteration: 0 (first iteration) +// Output: Current iteration: 2 (third iteration) +``` + +--- + +### `rq.info.iterationCount` + +**Type:** `number` + +The total number of iterations configured for the collection run. For single request executions, this value is `1`. + +**Example:** +```javascript +console.log(`Running iteration ${rq.info.iteration + 1} of ${rq.info.iterationCount}`); +// Output: Running iteration 3 of 10 +``` + +--- + +## Use Cases + +### Track Progress in Collection Runs + +```javascript +// Pre-request script +const progress = ((rq.info.iteration + 1) / rq.info.iterationCount * 100).toFixed(1); +console.log(`Progress: ${progress}% (${rq.info.iteration + 1}/${rq.info.iterationCount})`); +``` + +### Conditional Logic Based on Iteration + +```javascript +// Skip authentication on first iteration +if (rq.info.iteration === 0) { + console.log("First iteration - setting up authentication"); + rq.environment.set("authToken", "initial-token"); +} else { + console.log("Using existing authentication"); +} +``` + +### Different Behavior for First and Last Iterations + +```javascript +// Pre-request script +if (rq.info.iteration === 0) { + console.log("First iteration - initializing test data"); + rq.collectionVariables.set("testData", []); +} + +// Post-response script +if (rq.info.iteration === rq.info.iterationCount - 1) { + console.log("Last iteration - cleaning up"); + const allData = rq.collectionVariables.get("testData"); + console.log("Collected data from all iterations:", allData); +} +``` + +### Log Request Context + +```javascript +// Post-response script +console.log(`[${rq.info.requestName}] Status: ${rq.response.code} | Iteration: ${rq.info.iteration + 1}/${rq.info.iterationCount}`); +``` + +--- + +## Notes + +- The `iteration` property is **0-based** (starts from 0, not 1) +- For single request executions, `iteration` is `0` and `iterationCount` is `1` +- The `rq.info` object is read-only and cannot be modified +- All properties are available in both pre-request and post-response scripts diff --git a/general/api-client/rq-api-reference/rq-iteration-data.mdx b/general/api-client/rq-api-reference/rq-iteration-data.mdx new file mode 100644 index 0000000..08ec4cc --- /dev/null +++ b/general/api-client/rq-api-reference/rq-iteration-data.mdx @@ -0,0 +1,216 @@ +--- +title: rq.iterationData +label: rq.iterationData +slug: rq-iteration-data +description: Access data from CSV or JSON files during collection runs in Requestly API client scripts. +seoDescription: Access data from CSV or JSON files during collection runs in Requestly API client scripts. +visibility: PUBLIC +--- + +The `rq.iterationData` object provides access to data from CSV or JSON files when running collections with the Collection Runner. Each iteration of the collection run receives a different row (CSV) or object (JSON) from the data file, allowing you to parameterize your requests dynamically. + + +This feature is only available when running collections with a data file attached. For single request executions or collection runs without data files, `rq.iterationData` will be empty. + + +## Methods + +### `rq.iterationData.get(key)` + +Retrieves the value for a specific key from the current iteration's data. + +**Parameters:** +- `key` (string): The name of the variable/column to retrieve + +**Returns:** The value associated with the key, or `undefined` if the key doesn't exist + +**Example:** +```javascript +// For a CSV with columns: city, temperature +const city = rq.iterationData.get("city"); +const temp = rq.iterationData.get("temperature"); + +console.log(`Weather in ${city}: ${temp}°C`); +// Output: Weather in Vancouver: 10°C +``` + +--- + +### `rq.iterationData.has(key)` + +Checks if a specific key exists in the current iteration's data. + +**Parameters:** +- `key` (string): The name of the variable/column to check + +**Returns:** `true` if the key exists, `false` otherwise + +**Example:** +```javascript +if (rq.iterationData.has("userId")) { + const userId = rq.iterationData.get("userId"); + console.log("User ID:", userId); +} else { + console.log("No user ID in this iteration"); +} +``` + +--- + +### `rq.iterationData.toObject()` + +Returns all data from the current iteration as a JavaScript object. + +**Returns:** An object containing all key-value pairs from the current iteration + +**Example:** +```javascript +const allData = rq.iterationData.toObject(); +console.log("Current iteration data:", allData); +// Output: Current iteration data: { city: "Vancouver", temperature: 10 } +``` + +--- + +## Use Cases + +### Using Data File Values in Requests + +```javascript +// Pre-request script +// Assuming CSV has columns: username, password +const username = rq.iterationData.get("username"); +const password = rq.iterationData.get("password"); + +// Set as environment variables to use in request +rq.environment.set("currentUser", username); +rq.environment.set("currentPassword", password); +``` + +Then in your request body: +```json +{ + "username": "{{currentUser}}", + "password": "{{currentPassword}}" +} +``` + +### Conditional Logic Based on Data + +```javascript +// Pre-request script +const userType = rq.iterationData.get("userType"); + +if (userType === "admin") { + rq.request.headers.push({ + key: "X-Admin-Token", + value: "admin-secret-token" + }); +} else { + rq.request.headers.push({ + key: "X-User-Token", + value: "user-token" + }); +} +``` + +### Validating Response Against Expected Data + +```javascript +// Post-response script +const expectedStatus = rq.iterationData.get("expectedStatus"); +const actualStatus = rq.response.code; + +rq.test(`Status code matches expected (${expectedStatus})`, function() { + rq.expect(actualStatus).to.equal(parseInt(expectedStatus)); +}); +``` + +### Collecting Results from Multiple Iterations + +```javascript +// Post-response script +const results = rq.collectionVariables.get("results") || []; +const currentData = rq.iterationData.toObject(); + +results.push({ + iteration: rq.info.iteration, + input: currentData, + output: rq.response.json(), + status: rq.response.code +}); + +rq.collectionVariables.set("results", results); + +// On last iteration, log all results +if (rq.info.iteration === rq.info.iterationCount - 1) { + console.log("All results:", JSON.stringify(results, null, 2)); +} +``` + +### Dynamic URL Construction + +```javascript +// Pre-request script +const endpoint = rq.iterationData.get("endpoint"); +const id = rq.iterationData.get("id"); + +// Modify the request URL +rq.request.url = `https://api.example.com/${endpoint}/${id}`; +``` + +--- + +## Data File Format Examples + +### CSV Format + +```csv +city,temperature,humidity +Vancouver,10,75 +Austin,24,60 +London,12,80 +``` + +**Accessing in script:** +```javascript +const city = rq.iterationData.get("city"); // "Vancouver" +const temp = rq.iterationData.get("temperature"); // 10 +const humidity = rq.iterationData.get("humidity"); // 75 +``` + +### JSON Format + +```json +[ + { "city": "Vancouver", "temperature": 10, "humidity": 75 }, + { "city": "Austin", "temperature": 24, "humidity": 60 }, + { "city": "London", "temperature": 12, "humidity": 80 } +] +``` + +**Accessing in script:** +```javascript +const city = rq.iterationData.get("city"); // "Vancouver" +const temp = rq.iterationData.get("temperature"); // 10 +const humidity = rq.iterationData.get("humidity"); // 75 +``` + +--- + +## Notes + +- `rq.iterationData` is read-only and cannot be modified +- Data is automatically loaded from the attached CSV or JSON file +- Each iteration receives a different row/object from the data file +- For single request executions, `rq.iterationData` will be empty +- Values are automatically type-converted (numbers remain numbers, strings remain strings) +- Missing keys return `undefined` when accessed with `get()` + +--- + +## Related Documentation + +- [Collection Runner with Data Files](/general/api-client/collection-runner-data-file) - Learn how to attach and use data files +- [rq.info](/general/api-client/rq-api-reference/rq-info) - Access iteration metadata +- [Collection Runner](/general/api-client/collection-runner) - Overview of running collections diff --git a/general/api-client/scripts.mdx b/general/api-client/scripts.mdx index fd072d5..e1c8768 100644 --- a/general/api-client/scripts.mdx +++ b/general/api-client/scripts.mdx @@ -222,6 +222,33 @@ rq.test("Response has user data", function() { ---- +#### `rq.info` +Access execution metadata including request name, iteration index, and event name. Useful for tracking progress in collection runs and implementing iteration-specific logic. + +**Quick Example:** +```jsx +console.log(`Running ${rq.info.requestName}`); +console.log(`Iteration ${rq.info.iteration + 1} of ${rq.info.iterationCount}`); +``` + +[View complete rq.info documentation →](/general/api-client/rq-api-reference/rq-info) + +---- + +#### `rq.iterationData` +Access data from CSV or JSON files during collection runs. Each iteration receives different data from the file, enabling data-driven testing. + +**Quick Example:** +```jsx +const city = rq.iterationData.get("city"); +const temp = rq.iterationData.get("temperature"); +console.log(`Weather in ${city}: ${temp}°C`); +``` + +[View complete rq.iterationData documentation →](/general/api-client/rq-api-reference/rq-iteration-data) + +---- + ### Variable Scope Hierarchy When variables with the same name exist at multiple levels, the priority is: