Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/oleiade/xk6-exec
A k6 extension to execute shell commands from your k6 scripts
https://github.com/oleiade/xk6-exec
exec extension k6 performance-testing shell xk6
Last synced: 3 days ago
JSON representation
A k6 extension to execute shell commands from your k6 scripts
- Host: GitHub
- URL: https://github.com/oleiade/xk6-exec
- Owner: oleiade
- License: agpl-3.0
- Created: 2023-05-15T07:54:51.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2023-05-15T08:00:57.000Z (over 1 year ago)
- Last Synced: 2024-10-24T13:58:36.271Z (25 days ago)
- Topics: exec, extension, k6, performance-testing, shell, xk6
- Language: Go
- Homepage:
- Size: 27.3 KB
- Stars: 5
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# k6 Extension - Exec
This extension for k6 allows you to execute shell commands from your k6 scripts.
It exposes a new global object `Cmd` in the k6 JavaScript context, which can be used to construct commands.
## Installation
First, you need to install [xk6](https://github.com/k6io/xk6) and then build the k6 binary with the exec extension.
To install xk6, run:
```bash
go install github.com/grafana/xk6/cmd/xk6@latest
```
Then build the k6 binary:
```bash
xk6 build --with github.com/oleiade/xk6-exec@latest
```
This will result in a `k6` binary in the current directory.
## Usage
After you've built the `k6` binary, you can use it to run your scripts that use the `exec` extension. Here's a simple example:
```javascript
import { check } from "k6";
import { Cmd } from "k6/x/cmd";
export default async function () {
// Produce the command you wish to run
// using the composable API.
const cmd = new Cmd("motus")
.arg("memorable")
.arg("--words")
.arg("12")
.env("NO_COLOR", "true");
// Execute the command and wait for it to finish.
const result = await cmd.exec();
// Check the result of the command.
check(result, {
"exit code is 0": (r) => r.exitCode === 0,
"stdout contains 12 words": (r) => r.stdout.split(" ").length === 12,
});
}
```
In the above script, we're creating a new `Cmd` object with the command `motus`. We add arguments to the command using the `Arg` method. We add environment variables using the `Env` method. Then we execute the command with the `Exec` method, which returns a promise that resolves with the command's result.
## Metrics
The exec extension also provides custom k6 metrics:
- `exec_command_duration`: The duration of the command execution.
- `exec_commands_total`: The total number of executed commands.
- `exec_command_stdout_bytes`: The total number of bytes written to stdout by the command.
- `exec_command_stderr_bytes`: The total number of bytes written to stderr by the command.
- `exec_command_failed_rate`: The rate of command executions that failed.
These metrics are exposed to k6 and will appear in the summary at the end of a k6 test execution.
## Caution
This extension is potentially unsafe as it allows scripts to execute arbitrary commands on the system running k6. Use it responsibly and avoid running untrusted scripts.