The CLI Library

/* @provengo summon cli */

The CLI library allows automation of test steps using execution of external programs in a shell. Anything that can be achieved via a command line interface can be done with Provengo using this library (thus the name). A common use case is to invoke external interpreters, such as python, for executing certain test steps.

A simple example

Windows (CMD)

/* @provengo summon cli */  (1)

bthread('Create a directory and delete it', function () {
    let cmd = new CliSession("cmd", {workingDir: "c:\test"});               (2)
    cmd.doRun("cmd /c mkdir", CliSession.expectedExitCodes(0), 50000);        (3)
    cmd.doRun("cmd /c dir", CliSession.expectedExitCodes(0, 1, 2));           (4)
    cmd.doRun("cmd /c rmdir myDir", CliSession.expectedExitCodes([0, 1, 2])); (5)
});

1	Summons the CLI library.
2	Create cliSession object
3	Creates a directory named `myDir`, expect exit code to be `0, 1, 2`, set timeout of 5 seconds.
4	Verifies that the directory exists, expect exit code to be `0, 1, 2`.
5	Deletes the directory.

Unix

Same as above, but uses a Unix shell.

bthread('Create a directory and delete it', function () {
    let cmd = new CliSession("cmd", {workingDir: "/Users/provengo"});               (1)
    cmd.doRun("mkdir myDir", CliSession.expectedExitCodes(0), 50000);
    cmd.doRun("ls", CliSession.expectedExitCodes(0));
    cmd.doRun("rmdir myDir", CliSession.expectedExitCodes(0))
});

`CliSession(name, options)`

Constructs a new cli session.

name

cli session name

options

Optional options:

workingDir: path to executed in it the command.
environmentVariables: map of environment variables.

Methods

`cli.doRun(command, callback, timeout)`

Execute the command in the local shell. Check for the expected return codes. The command is executed at the project’s directory as default(in other words: the working directory is the project’s directory). in order to execute the command in other path, define the workingDir on the constructor.

command

String of the command to execute.

callback

Validation function for the cli run result: callback(runResult). This function can report back to the program using the pvg service object, exposed as a global variable.

runResult

execution exit object.

exitCode: execution exit value (number).
nextLine: get the next line from the cli output (string).
nextLines: get all the remaining lines of the cli output (string).
hasNextLine: returns true when there is at least one more line to read from the cli output, otherwise returns false (boolean).

timeout

Specifies how long should Provengo wait for the command before declaring a timeout (in milliseconds). This parameter is optional, and defaults to 10,000 milliseconds.

Example

Calling the cowsay program and reporting its results. This is a part of a bigger model; populating the runtime variables and requesting the Ctrl.markEvent are performed by other bthreads.

bthread("cowsayDriver", function(){
    waitFor(Ctrl.markEvent("Ingredients Set"));

    cliSession.doRun("cowsay preparing @{main} and @{extras} in a @{flourType} tortilla",
        function(output) {
            const retCode = output.exitCode;
            pvg.log.info(`cli output: ${output.allLines}`);                     (1)
            pvg.log.info(`Return code: ${retCode}`);                     (2)
            pvg.rtv.set("cowsayRetCodeHash", retCode*79+13);             (3)

            if (retCode !== 0) {
                pvg.error("cowsay failed with return code " + retCode);  (4)
            }
            pvg.success("cow generated successfully");                   (5)
        }
    );
});

1	`pvg` used to write a message to the log, at the `INFO` logging level.
2	`pvg.rtv` used to set a runtime variable.
3	If the return code is not `0`, `pvg.error` is used to halt scenario execution, and to mark its result as `ERROR`, noting the passed message.
4	`pvg.success` is used to provide some note on why is the test step successful.

`CliSession.expectedExitCodes(exitCodes)`

exitCodes: validates that invoked process exited with one of the values in exitCodes. exitCodes could be number, several numbers or an array of numbers.

    CliSession.expectedExitCodes(0)
    CliSession.expectedExitCodes(0, 1, 2)
    CliSession.expectedExitCodes([0, 1, 2])

`cli.runEvent(command, callback, timeout)`

Cli run event.