Interacting with the environment

In addition to screenshot-based test actions, Sakuli is capable of utilizing your keyboard, clipboard and environment variables. All these features are incorporated in the Environment class.

Keyboard actions

The following snippet shows a possible use-case for native keyboard actions. When initiating a download in Firefox, a native file download dialog opens. To start the download, we need to accept the file dialog, something that is not possible within the capabilities of Selenium. With Sakuli you get the opportunity to work around this problem, just like a real user would do. We can accept the file dialog by simply pressing the Enter button. Use Firefox as a browser for this test to work, as Chrome simply downloads the file without user interaction:

(async () => {
    const testCase = new TestCase("test");
    const url = "";
    const env = new Environment();
    try {
        await _navigateTo(url);
        await _click(_link("ABOUT"));
        await _click(_link("Releases"));
        await _click(_link("Dubnium"));
        await _highlight(_link(/node-v10.\d{1,}.\d{1,}.tar.gz/));
        await _click(_link(/node-v10.\d{1,}.\d{1,}.tar.gz/));
        await _wait(3000); //wait for browser pop-up to activate
        await env.keyDown(Key.ENTER);
        await env.keyUp(Key.ENTER);
    } catch (e) {
        await testCase.handleException(e);
    } finally {

It is even possible to change the download location dynamically in some environments, by entering a new save path via:

await env.type("/new/path/to/file");


Many E2E tests require some kind of login. While there is no problem in general, it still requires some mechanism to handle credentials. Providing credentials via environment variable is a common practice, but it still is inconvenient when deploying the testcase to another system, since every single environment variable has to be migrated too.

Sakuli comes with a built-in mechanism to deal with sensitive data in testcases. It uses a single masterkey, generated by Sakuli itself, to de- or encrypt secrets used in testcases.


npx sakuli create masterkey

will generate a new masterkey, which should be exported as an environment variable SAKULI_ENCRYPTION_KEY.

Once the masterkey has been exported, secrets can be encrypted by running:

npx sakuli encrypt "super secret string"

These encrypted secrets can now be stored safely inside your testfile. The Environment class provides methods to decrypt these secrets during test execution.

await env.typeAndDecrypt("$ENCRYPTED_SECRET");
// alternatively, via clipboard
await env.pasteAndDecrypt("$ENCRYPTED_SECRET");