Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

add docs for new async check function in k6-utils #1694

Merged
merged 3 commits into from
Aug 21, 2024
Merged

add docs for new async check function in k6-utils #1694

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
c58f118
add docs for new async check function in k6-utils
allansson Aug 16, 2024
a0a3fb0
apply patch to v0.53.0
allansson Aug 16, 2024
3bbc11d
update with suggestions
allansson Aug 20, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions docs/sources/next/javascript-api/jslib/utils/_index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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/<K6_VERSION>/javascript-api/jslib/utils/check) | Drop-in replacement for [`check`](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6/check/) with support for async values. |
| [randomIntBetween(min, max)](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/jslib/utils/randomintbetween) | Random integer in a given range |
| [randomItem(array)](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/jslib/utils/randomitem) | Random item from a given array |
| [randomString(length, [charset])](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/jslib/utils/randomstring) | Random string of a given length, optionally selected from a custom character set |
Expand Down
61 changes: 61 additions & 0 deletions docs/sources/next/javascript-api/jslib/utils/check.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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/<K6_VERSION>/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<string, any> | Tests (checks) to run on the value. Functions will be called. `Promise`s will be awaited. |
| tags (optional) | Record<string, string> | Extra tags to attach to metrics emitted. |

### Returns

| Type | Description |
| ---------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| Promise<boolean> | 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/<K6_VERSION>/javascript-api/k6/check/#examples).
1 change: 1 addition & 0 deletions docs/sources/v0.53.x/javascript-api/jslib/utils/_index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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/<K6_VERSION>/javascript-api/jslib/utils/check) | Drop-in replacement for [`check`](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6/check/) with support for async values. |
| [randomIntBetween(min, max)](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/jslib/utils/randomintbetween) | Random integer in a given range |
| [randomItem(array)](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/jslib/utils/randomitem) | Random item from a given array |
| [randomString(length, [charset])](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/jslib/utils/randomstring) | Random string of a given length, optionally selected from a custom character set |
Expand Down
61 changes: 61 additions & 0 deletions docs/sources/v0.53.x/javascript-api/jslib/utils/check.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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/<K6_VERSION>/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<string, any> | Tests (checks) to run on the value. Functions will be called. `Promise`s will be awaited. |
| tags (optional) | Record<string, string> | Extra tags to attach to metrics emitted. |

### Returns

| Type | Description |
| ---------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| Promise<boolean> | 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/<K6_VERSION>/javascript-api/k6/check/#examples).
Loading