Archive k6 v0.44.0 JS API docs

Author: mstoykov

src/data/markdown/versioned-js-api/v0.44/javascript api/01 Init context.md

@@ -0,0 +1,12 @@
+---
+title: "Init context"
+excerpt: 'The init context (aka "init code") is code in the global context that has access to a few functions not accessible during main script execution.'
+---
+
+Before the k6 starts the test logic, code in the _init context_ prepares the script.
+A few functions are available only in init context.
+For details about the runtime, refer to the [Test lifecycle](/using-k6/test-lifecycle).
+
+| Function                                                                              | Description         |
+| ----------------------------------------------------------------------------------- | --------------------- |
+| [open( filePath, [mode] )](/javascript-api/init-context/open) | Opens a file and reads all the contents into memory. |

src/data/markdown/versioned-js-api/v0.44/javascript api/01 Init context/open.md

@@ -0,0 +1,112 @@
+---
+head_title: 'JavaScript API: open'
+title: 'open( filePath, [mode] )'
+description: 'Opens a file and reads all the contents into memory.'
+excerpt: 'Opens a file and reads all the contents into memory.'
+---
+
+Opens a file, reading all its contents into memory for use in the script.
+
+> #### Use [SharedArray](/javascript-api/k6-data/sharedarray/) for CSV and JSON files
+> `open()` often consumes a large amount of memory because every VU keeps a separate copy of the file in memory.
+> To reduce the memory consumption, we strongly advise the usage of [SharedArray](/javascript-api/k6-data/sharedarray/) for CSV, JSON and other files intended for script parametrization.
+
+<blockquote mod='attention' title='Function available only in init context'>
+
+This function can only be called from the init context (aka _init code_), code in the global context that is, outside of the main export default function { ... }.
+
+By restricting it to the init context, we can easily determine what local files are needed to run the test and thus what we need to bundle up when distributing the test to multiple nodes in a clustered/distributed test.
+
+See the example further down on this page. For a more in-depth description, see [Test lifecycle](/using-k6/test-lifecycle).
+
+</blockquote>
+
+| Parameter | Type   | Description        |
+| --------- | ------ | ------------------ |
+| filePath  | string | The path to the file, absolute or relative, that will be read into memory. The file will only be loaded once, even when running with several VUs. |
+| mode      | string | By default, the contents of the file are read as text, but if you specify `b`, the file will be read as binary data instead.   |
+
+### Returns
+
+| Type                 | Description                                                                                     |
+| ----                 | -----------                                                                                     |
+| string / ArrayBuffer | The contents of the file, returned as string or ArrayBuffer (if `b` was specified as the mode). |
+
+
+<CodeGroup labels={["users.json"]}>
+
+```json
+[
+  {
+    "username": "user1",
+    "password": "password1"
+  },
+  {
+    "username": "user2",
+    "password": "password2"
+  },
+  {
+    "username": "user3",
+    "password": "password3"
+  }
+]
+```
+
+</CodeGroup>
+
+<CodeGroup labels={["Loading JSON data with SharedArray to parameterize test"]}>
+
+```javascript
+import { SharedArray } from 'k6/data';
+import { sleep } from 'k6';
+
+const data = new SharedArray('users', function () {
+  // here you can open files, and then do additional processing or generate the array with data dynamically
+  const f = JSON.parse(open('./users.json'));
+  return f; // f must be an array[]
+});
+
+export default () => {
+  const randomUser = data[Math.floor(Math.random() * data.length)];
+  console.log(`${randomUser.username}, ${randomUser.password}`);
+  sleep(3);
+};
+```
+
+</CodeGroup>
+
+<CodeGroup labels={["Loading JSON data without SharedArray"]}>
+
+```javascript
+import { sleep } from 'k6';
+
+const users = JSON.parse(open('./users.json')); // consider using SharedArray for large files
+
+export default function () {
+  const user = users[__VU - 1];
+  console.log(`${user.username}, ${user.password}`);
+  sleep(3);
+}
+```
+
+</CodeGroup>
+
+<CodeGroup labels={["Loading a binary file and POSTing it as a multipart request"]}>
+
+```javascript
+import http from 'k6/http';
+import { sleep } from 'k6';
+
+const binFile = open('/path/to/file.bin', 'b');
+
+export default function () {
+  const data = {
+    field: 'this is a standard form field',
+    file: http.file(binFile, 'test.bin'),
+  };
+  const res = http.post('https://example.com/upload', data);
+  sleep(3);
+}
+```
+
+</CodeGroup>

src/data/markdown/versioned-js-api/v0.44/javascript api/02 k6.md

@@ -0,0 +1,14 @@
+---
+title: 'k6'
+excerpt: 'The k6 module contains k6-specific functionality.'
+---
+
+The k6 module contains k6-specific functionality.
+
+| Function                                                           | Description                                                                                                                                  |
+| ------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| [check(val, sets, [tags])](/javascript-api/k6/check) | Runs one or more checks on a value and generates a pass/fail result but does not throw errors or otherwise interrupt execution upon failure. |
+| [fail([err])](/javascript-api/k6/fail)                         | Throws an error, failing and aborting the current VU script iteration immediately.                                                           |
+| [group(name, fn)](/javascript-api/k6/group)                | Runs code inside a group. Used to organize results in a test.                                                                                |
+| [randomSeed(int)](/javascript-api/k6/randomseed)               | Set seed to get a reproducible pseudo-random number using `Math.random`.                                                                     |
+| [sleep(t)](/javascript-api/k6/sleep)                             | Suspends VU execution for the specified duration.                                                                                            |

src/data/markdown/versioned-js-api/v0.44/javascript api/02 k6/check- val- sets- -tags- -.md

@@ -0,0 +1,72 @@
+---
+title: 'check( val, sets, [tags] )'
+description: 'Runs one or more checks on a value and generates a pass/fail result but does not throw errors or otherwise interrupt execution upon failure.'
+excerpt: 'Runs one or more checks on a value and generates a pass/fail result but does not throw errors or otherwise interrupt execution upon failure.'
+---
+
+Run checks on a value. A check is a test condition that can give a truthy or
+falsy result. The `sets` parameter contains one or more checks, and the `check()`
+function will return `false` if any of them fail.
+
+Note that checks are not _asserts_ in their traditional sense - a failed assertion
+will throw an error, while a check will always return with a pass or a failure.
+Failure conditions can then instead be controlled by thresholds, for more power and flexibility.
+
+| Parameter       | Type   | Description                              |
+| --------------- | ------ | ---------------------------------------- |
+| val             | any    | Value to test.                           |
+| sets            | object | Tests (checks) to run on the value.      |
+| tags (optional) | object | Extra tags to attach to metrics emitted. |
+
+### Returns
+
+| Type    | Description                                             |
+| ------- | ------------------------------------------------------- |
+| boolean | `true` if all checks have succeeded, `false` otherwise. |
+
+### Examples
+
+Using `check()` to verify that an HTTP response code was 200:
+
+<CodeGroup labels={[]}>
+
+```javascript
+import http from 'k6/http';
+import { check } from 'k6';
+
+export default function () {
+  const res = http.get('https://httpbin.test.k6.io');
+  check(res, {
+    'response code was 200': (res) => res.status == 200,
+  });
+}
+```
+
+</CodeGroup>
+
+Using `check()` with a custom tag to verify that an HTTP response code was 200 and that body was 1234 bytes. The `checkOutput` can be used for any condition in your script logic:
+
+<CodeGroup labels={[]}>
+
+```javascript
+import http from 'k6/http';
+import { check, fail } from 'k6';
+
+export default function () {
+  const res = http.get('https://httpbin.test.k6.io');
+  const checkOutput = check(
+    res,
+    {
+      'response code was 200': (res) => res.status == 200,
+      'body size was 1234 bytes': (res) => res.body.length == 1234,
+    },
+    { myTag: "I'm a tag" }
+  );
+
+  if (!checkOutput) {
+    fail('unexpected response');
+  }
+}
+```
+
+</CodeGroup>

src/data/markdown/versioned-js-api/v0.44/javascript api/02 k6/fail- -err- -.md

@@ -0,0 +1,41 @@
+---
+title: 'fail( [err] )'
+description: 'Throws an error, failing and aborting the current VU script iteration immediately.'
+excerpt: 'Throws an error, failing and aborting the current VU script iteration immediately.'
+---
+
+Immediately throw an error, aborting the current iteration. 
+
+`fail()` does not abort the test, nor does it make the test exit with non-0 status.
+If you are looking to fail the test by halting the execution, use [test.abort()](/javascript-api/k6-execution/#test) instead
+
+`fail()` is a simple convenience wrapper on top of JavaScript's `throw()`,
+because the latter cannot be used as `[expr] || throw`, which is a convenient way to write k6 test code.
+
+| Parameter      | Type   | Description                                |
+| -------------- | ------ | ------------------------------------------ |
+| err (optional) | string | Error message that gets printed to stderr. |
+
+### Example
+
+Aborting the current script iteration if a check fails:
+
+<CodeGroup labels={[]}>
+
+```javascript
+import http from 'k6/http';
+import { check, fail } from 'k6';
+
+export default function () {
+  const res = http.get('https://k6.io');
+  if (
+    !check(res, {
+      'status code MUST be 200': (res) => res.status == 200,
+    })
+  ) {
+    fail('status code was *not* 200');
+  }
+}
+```
+
+</CodeGroup>

src/data/markdown/versioned-js-api/v0.44/javascript api/02 k6/group- name- fn -.md

@@ -0,0 +1,65 @@
+---
+title: 'group( name, fn )'
+description: 'Runs code inside a group. Used to organize results in a test.'
+excerpt: 'Runs code inside a group. Used to organize results in a test.'
+---
+
+Run code inside a group. Groups are used to organize results in a test.
+
+| Parameter | Type     | Description                                            |
+| --------- | -------- | ------------------------------------------------------ |
+| name      | string   | Name of the group.                                     |
+| fn        | function | Group body - code to be executed in the group context. |
+
+### Returns
+
+| Type | Description               |
+| ---- | ------------------------- |
+| any  | The return value of _fn_. |
+
+<Blockquote mod="warning" title="Working with async functions">
+
+Avoid using `group` with async functions or asynchronous code.
+If you do, k6 might apply tags in a way that is unreliable or unintuitive.
+
+If you start promise chains or even use `await` within `group`, some code within the group will be waited for and tagged with the proper `group` tag, but others won't be.
+
+To avoid confusion, `async` functions are forbidden as `group()` arguments. This still lets users make and chain promises within a group, but doing so is unsupported and not recommended.
+
+For more information, refer to [k6 #2728](https://github.com/grafana/k6/issues/2728), which tracks possible solutions and provides detailed explanations.
+
+</Blockquote>
+
+### Example
+
+<CodeGroup labels={[]}>
+
+```javascript
+import { group } from 'k6';
+
+export default function () {
+  group('visit product listing page', function () {
+    // ...
+  });
+  group('add several products to the shopping cart', function () {
+    // ...
+  });
+  group('visit login page', function () {
+    // ...
+  });
+  group('authenticate', function () {
+    // ...
+  });
+  group('checkout process', function () {
+    // ...
+  });
+}
+```
+
+</CodeGroup>
+
+The above code will present the results separately depending on the group execution.
+
+Learn more on [Groups and Tags](/using-k6/tags-and-groups).
+
+

src/data/markdown/versioned-js-api/v0.44/javascript api/02 k6/images/groups.png

@@ -0,0 +1,34 @@
+---
+title: 'randomSeed( int )'
+description: 'Set seed to get a reproducible pseudo-random number using `Math.random`.'
+excerpt: 'Set seed to get a reproducible pseudo-random number using `Math.random`.'
+---
+
+Set seed to get a reproducible pseudo-random number using `Math.random`.
+
+| Parameter | Type    | Description     |
+| --------- | ------- | --------------- |
+| int       | integer | The seed value. |
+
+### Example
+
+Use `randomSeed` to get the same random number in all the iterations.
+
+<CodeGroup labels={[]}>
+
+```javascript
+import { randomSeed } from 'k6';
+
+export const options = {
+  vus: 10,
+  duration: '5s',
+};
+
+export default function () {
+  randomSeed(123456789);
+  const rnd = Math.random();
+  console.log(rnd);
+}
+```
+
+</CodeGroup>