This module provides functionality for driving Cinnamon user interface in an automated fashion. The primary current use case for this is automated performance testing (see runPerfScript()), but it could be applied to other forms of automation, such as testing for correctness as well.
When scripting an automated test we want to make a series of calls in a linear fashion, but we also want to be able to let the main loop run so actions can finish. For this reason we write the script as a generator function that yields when it want to let the main loop run.
yield Scripting.sleep(1000); main.overview.show(); yield Scripting.waitLeisure();
While it isn't important to the person writing the script, the actual yielded result is a function that the caller uses to provide the callback for resuming the script.
Used within an automation script to pause the the execution of the current script for the specified amount of time. Use as 'yield Scripting.sleep(500);'
Used within an automation script to pause the the execution of the current script until Cinnamon is completely idle. Use as 'yield Scripting.waitLeisure();'
Creates a window using cinnamon-perf-helper for testing purposes. While this function can be used with yield in an automation script to pause until the D-Bus call to the helper process returns, because of the normal X asynchronous mapping process, to actually wait until the window has been mapped and exposed, use waitTestWindows().
Used within an automation script to pause until all windows previously created with createTestWindow have been mapped and exposed.
Destroys all windows previously created with createTestWindow(). While this function can be used with yield in an automation script to pause until the D-Bus call to the helper process returns, this doesn't guarantee that Muffin has actually finished the destroy process because of normal X asynchronicity.
Convenience function to define a zero-argument performance event within the 'script' namespace that is reserved for events defined locally within a performance automation script
Convenience function to record a script-local performance event previously defined with defineScriptEvent
First the run() function within the module will be called as a generator to automate a series of actions. These actions will trigger performance events and the script can also record its own performance events.
Then the recorded event log is replayed using handler functions within the module. The handler for the event 'foo.bar' is called foo_bar().
Finally if the module has a function called finish(), that will be called.
The event handler and finish functions are expected to fill in metrics to an object within the module called METRICS. Each property of this object represents an individual metric. The name of the property is the name of the metric, the value of the property is an object with the following properties:
description: human readable description of the metric units: a string representing the units of the metric. It has the form '<unit> <unit> ... / <unit> / <unit> ...'. Certain unit values are recognized: s, ms, us, B, KiB, MiB. Other values can appear but are uninterpreted. Examples 's', '/ s', 'frames', 'frames / s', 'MiB / s / frame' value: computed value of the metric
The resulting metrics will be written to
outputFile as JSON, or, if
outputFile is not provided, logged.
After running the script and collecting statistics from the event log, Cinnamon will exit.