Provide an API to exit a test

[ppcano]

The k6 API does not provide an API to exit a load test. The fail does not cover this case.

A common workaround is to configure a threshold that aborts the test when the threshold is crossed.

import { sleep } from "k6";
import http from "k6/http";
import { Counter } from "k6/metrics";

export let options = {
    stages: [
        { duration: "30s", target: 50 }
    ],
    thresholds: {
        "myThresholdMetric": [{threshold: "count<1", abortOnFail: true}]
    }
};

const myThresholdMetric = new Counter("myThresholdMetric");

export default function() {
    http.get("https://test.loadimpact.com/");
    if (__VU === 1 && __ITER === 1) { 
        myThresholdMetric.add(1);
    }
    sleep(3);
};

But this or other workarounds have a few inconveniences or limitations:

1. The Threshold API works well for evaluating complex conditions but the API is not intuitive or simple when you want just to check a simple condition.

    if (condition) { 
        exit();
    }

2. It cannot exit the load test on a non-error mode.

exit(0);

3. It cannot provide different exit codes. Related issue: Different exit codes for different errors

exit(5);

4. it cannot provide user message

exit(10, “service was not available”);

5. The API should also work on the setup/teardown methods.

export function teardown(time) {
    if (condition) { 
        exit(1);
    }
}

The exit API is a suggestion, but in any case, I think it could be a good addition if k6 provides an API to support these cases during local and cloud execution. Some users have already asked for a similar utility.

[na--]

This is a partial duplicate of an older issue, but I'll close the old one and leave this one open, since this is more detailed and somewhat easier to find. Just a couple of comments on the proposed API:

• I prefer abort() as the name of the new function, as proposed in the other issue. It's makes it more clear that we're aborting the whole test. exit() also has connotations of immediate termination, while k6 actually has to perform some housekeeping when it aborts tests, like sending latest metrics to collectors, etc.
• This likely shouldn't be a global function, rather it would probably be better if users have to import it as import { abort, sleep } from "k6";

[RobinHoutevelts]

Since we now have the powerful scenario's. Would it be possible to abort a scenario so the next one starts?

That would be a massive win for me.

[na--]

We discussed this a bit internally, and this is the specification we arrived at:

• The function name should be abortTest() and it should be in the root k6 JS module (i.e. it should be accessible from test scripts via import { abortTest } from 'k6').
• Once called, abortTest() should stop the whole test run and the k6 process should exit with a custom fixed non-zero exit code 107.
• In contrast to the old way of stopping the test run (a threshold on a custom metric with abortOnFail: true) mentioned above, abortTest() should make sure that the VU that called it stops immediately after, i.e. no more instructions from its current iteration are executed and no more iterations are started.
• The teardown() function should still be executed after the test run aborts in this way.
• The run status of the test run should be aborted by script (e.g. for when k6 run --out cloud is used)

So, a JS script that uses it should look somewhat like this:

import http from 'k6/http';
import { abortTest, sleep } from 'k6';

export default function () {
    // ... some test logic ...
    if (Math.random() < 0.01) { // or some actual test abort check
        console.log('mayday, mayday');
        abortTest();
        console.log('this should never be executed');
    }
    // ...
}

[basickarl]

Since we now have the powerful scenario's. Would it be possible to abort a scenario so the next one starts?

That would be a massive win for me.

I agree with this, this would be a total win here also! Something like abortScenario. My scenario needs to end once all users have received a specific HTTP response from the API we are testing, we are testing creation load in our backend.

[na--]

@basickarl, aborting a single scenario would be a lot more complicated in the distributed/cloud execution mode, so it's out of scope for this issue. If you want, feel free to create a new issue with details of your specific use case.