The pvg Callback Service Object

Callback functions, such as those used by the Commandline and the REST APIs libraries, often need to report their results, write logs, read and update Runtime Variables, and generally interact with the Provengo environment. The pvg object, made available through a global variable for these functions, allows doing just that.

Example

Consider a model for testing various burrito compositions. The burrito ingredients are stored in the runtime variables main, extras, and flourType. In the program snippet below, the cowsayDriver bthread waits for the data to be ready, and then runs cowsay with the proper prompt. The callback function uses the pvg object to set a runtime variable, report the call results, and print to the log.

pvg is accessed through a global variable, it is not passed to the callback as a parameter.
This is not a complete model! We assume some other bthreads are setting the runtime variable values, and then calling Ctrl.doMark("Ingredients Set"). 
bthread("cowsayDriver", function(){
    waitFor(Ctrl.markEvent("Ingredients Set"));

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

            if (retCode !== 0) {
                pvg.error("cowsay failed with return code " + retCode);  (3)
            }
            pvg.success("cow generated successfully");                   (4)
        }
    );
});
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.
Sample output

Below is a sample output of the above bthread. Note that we are not at all judgemental regarding that specific combination of ingredient.

[RUN>random] INFO Selected: [cli(cowsay preparing tofu and beans in a flour tortilla) ... ]
[RUN>random] FINE Executing command: cowsay preparing tofu and beans in a flour tortilla
[RUN>random] FINE  _____________________________________
[RUN>random] FINE / preparing tofu and beans in a flour \
[RUN>random] FINE \ tortilla                            /
[RUN>random] FINE  -------------------------------------
[RUN>random] FINE         \   ^__^
[RUN>random] FINE          \  (oo)\_______
[RUN>random] FINE             (__)\       )\/\
[RUN>random] FINE                 ||----w |
[RUN>random] FINE                 ||     ||
[RUN>random] FINE Exit value: 0
[RUN>random] INFO Return code: 0
[RUN>random] INFO RTV: setting 'cowsayRetCodeHash' to '13'
[RUN>random] FINE Actuator CLIActuator: Actuation:PASS
[RUN>random] FINE Event handling completed
[RUN>random] FINE Completed b-thread: cowsayDriver
If a callback function did not call pvg.fail(), pvg.error(), or pvg.success(), Provengo will consider it an OK result, meaning the callback did not perform any significant validations worth noting. Test scenario execution will continue as usual.

Methods

pvg.success()

Marks the callback as successful, without logging a message. Terminates the callback execution. Test scenario execution will continue.

pvg.success(message)

Marks the callback as successful, logging the passed message. Terminates the callback execution. Test scenario execution will continue.

pvg.fail(message)

Marks the test as failed, citing the passed message as the failure reason. Terminates execution of both callback and test scenario.

pvg.error(message)

Marks the test as errored, citing the passed message as the error description. Terminates execution of both callback and test scenario.

Fields

pvg.log

Provides access to the runtime logger. This logger writes to standard out, and has various logging levels. By default, logger level is set to INFO. This means that calls to pvg.log.fine are effectively ignored. When provengo is invoked with the --verbose flag, these calls do print passed messages.

pvg.log.fine(message)

Writes the passed message to standard out, when the logger level is FINE or higher (e.g. when invoking provengo with the --verbose flag). Since by default the messages are not printed, this method is ideal for logging fine-grained information, such as values and messages useful during model development but not during normal test execution.

pvg.log.info(message)

Writes the passed message to provengo’s standard out.

pvg.log.warn(message)

Writes the passed message to provengo’s standard out, marking it as a warning.

pvg.log.error(message)

Writes the passed message to provengo’s standard out, marking it as an error.

pvg.log.mark(message)

Writes the passed message to provengo’s standard out, giving it a bold color. Useful for marking specific values during development.

pvg.rtv

Provides access to the runtime values subsystem.

pvg.rtv.set(key, value)

Stores value under key.

pvg.rtv.get(key)

Returns the value stored under key.