diff --git a/docs/sources/next/javascript-api/jslib/utils/_index.md b/docs/sources/next/javascript-api/jslib/utils/_index.md index bb12a3cb55..34b68f3a78 100644 --- a/docs/sources/next/javascript-api/jslib/utils/_index.md +++ b/docs/sources/next/javascript-api/jslib/utils/_index.md @@ -13,6 +13,7 @@ The `utils` module contains number of small utility functions useful in every da | Function | Description | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [check(val, sets, [tags])](https://grafana.com/docs/k6//javascript-api/jslib/utils/check) | Drop-in replacement for [`check`](https://grafana.com/docs/k6//javascript-api/k6/check/) with support for async values. | | [randomIntBetween(min, max)](https://grafana.com/docs/k6//javascript-api/jslib/utils/randomintbetween) | Random integer in a given range | | [randomItem(array)](https://grafana.com/docs/k6//javascript-api/jslib/utils/randomitem) | Random item from a given array | | [randomString(length, [charset])](https://grafana.com/docs/k6//javascript-api/jslib/utils/randomstring) | Random string of a given length, optionally selected from a custom character set | diff --git a/docs/sources/next/javascript-api/jslib/utils/check.md b/docs/sources/next/javascript-api/jslib/utils/check.md new file mode 100644 index 0000000000..3ddb2fbc85 --- /dev/null +++ b/docs/sources/next/javascript-api/jslib/utils/check.md @@ -0,0 +1,61 @@ +--- +title: 'check( val, sets, [tags] )' +description: 'The jslib check function runs one or more checks on a value and generates a pass/fail result, but does not throw errors or interrupt test execution upon failure. It supports async values.' +--- + +# check( val, sets, [tags] ) + +The `check` function is a drop-in replacement for the built-in [check](https://grafana.com/docs/k6//javascript-api/k6/check/), with added support for async values. Any `Promise`s will be awaited, and the result is reported once the operation has been completed. + +| Parameter | Type | Description | +| --------------- | ---------------------- | ----------------------------------------------------------------------------------------- | +| val | any | Value to test. | +| sets | Record | Tests (checks) to run on the value. Functions will be called. `Promise`s will be awaited. | +| tags (optional) | Record | Extra tags to attach to metrics emitted. | + +### Returns + +| Type | Description | +| ---------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------- | +| Promise | boolean | `true` if all checks have succeeded, `false` otherwise. If any of the checked values was a `Promise`, the result is wrapped in a `Promise`. | + +### Examples + +Using `check()` with async values. + +{{< code >}} + +```javascript +import http from 'k6/http'; +import { fail } from 'k6'; +import { check } from 'https://jslib.k6.io/k6-utils/1.5.0/index.js'; + +function waitFor(delay) { + return new Promise((resolve) => { + setTimeout(() => { + resolve(true); + }, delay); + }); +} + +export default async function () { + const res = http.get('https://httpbin.test.k6.io'); + + const success = await check(res, { + 'passing promise as a value': waitFor(1000), + 'async function': async (res) => { + await waitFor(500); + + return res.status === 200; + }, + }); + + if (!success) { + fail('check did not succeed'); + } +} +``` + +{{< /code >}} + +For general usage of checks, refer to [check(val, set, [tags])](https://grafana.com/docs/k6//javascript-api/k6/check/#examples). diff --git a/docs/sources/v0.53.x/javascript-api/jslib/utils/_index.md b/docs/sources/v0.53.x/javascript-api/jslib/utils/_index.md index bb12a3cb55..34b68f3a78 100644 --- a/docs/sources/v0.53.x/javascript-api/jslib/utils/_index.md +++ b/docs/sources/v0.53.x/javascript-api/jslib/utils/_index.md @@ -13,6 +13,7 @@ The `utils` module contains number of small utility functions useful in every da | Function | Description | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [check(val, sets, [tags])](https://grafana.com/docs/k6//javascript-api/jslib/utils/check) | Drop-in replacement for [`check`](https://grafana.com/docs/k6//javascript-api/k6/check/) with support for async values. | | [randomIntBetween(min, max)](https://grafana.com/docs/k6//javascript-api/jslib/utils/randomintbetween) | Random integer in a given range | | [randomItem(array)](https://grafana.com/docs/k6//javascript-api/jslib/utils/randomitem) | Random item from a given array | | [randomString(length, [charset])](https://grafana.com/docs/k6//javascript-api/jslib/utils/randomstring) | Random string of a given length, optionally selected from a custom character set | diff --git a/docs/sources/v0.53.x/javascript-api/jslib/utils/check.md b/docs/sources/v0.53.x/javascript-api/jslib/utils/check.md new file mode 100644 index 0000000000..3ddb2fbc85 --- /dev/null +++ b/docs/sources/v0.53.x/javascript-api/jslib/utils/check.md @@ -0,0 +1,61 @@ +--- +title: 'check( val, sets, [tags] )' +description: 'The jslib check function runs one or more checks on a value and generates a pass/fail result, but does not throw errors or interrupt test execution upon failure. It supports async values.' +--- + +# check( val, sets, [tags] ) + +The `check` function is a drop-in replacement for the built-in [check](https://grafana.com/docs/k6//javascript-api/k6/check/), with added support for async values. Any `Promise`s will be awaited, and the result is reported once the operation has been completed. + +| Parameter | Type | Description | +| --------------- | ---------------------- | ----------------------------------------------------------------------------------------- | +| val | any | Value to test. | +| sets | Record | Tests (checks) to run on the value. Functions will be called. `Promise`s will be awaited. | +| tags (optional) | Record | Extra tags to attach to metrics emitted. | + +### Returns + +| Type | Description | +| ---------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------- | +| Promise | boolean | `true` if all checks have succeeded, `false` otherwise. If any of the checked values was a `Promise`, the result is wrapped in a `Promise`. | + +### Examples + +Using `check()` with async values. + +{{< code >}} + +```javascript +import http from 'k6/http'; +import { fail } from 'k6'; +import { check } from 'https://jslib.k6.io/k6-utils/1.5.0/index.js'; + +function waitFor(delay) { + return new Promise((resolve) => { + setTimeout(() => { + resolve(true); + }, delay); + }); +} + +export default async function () { + const res = http.get('https://httpbin.test.k6.io'); + + const success = await check(res, { + 'passing promise as a value': waitFor(1000), + 'async function': async (res) => { + await waitFor(500); + + return res.status === 200; + }, + }); + + if (!success) { + fail('check did not succeed'); + } +} +``` + +{{< /code >}} + +For general usage of checks, refer to [check(val, set, [tags])](https://grafana.com/docs/k6//javascript-api/k6/check/#examples).