Scripting

Scripting — Scripts for driving cinnamon in an automated fasion

Functions

Description

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.

Functions

sleep ()


sleep (int   milliseconds);

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);'

Parameters

milliseconds

number of milliseconds to wait

 

waitLeisure ()


waitLeisure ();

Used within an automation script to pause the the execution of the current script until Cinnamon is completely idle. Use as 'yield Scripting.waitLeisure();'


createTestWindow ()


createTestWindow (int       width,
                  int       height,
                  boolean   alpha,
                  boolean   maximized);

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().

Parameters

width

width of window, in pixels

 

height

height of window, in pixels

 

alpha

whether the window should be alpha transparent

 

maximized

whethe the window should be created maximized

 

waitTestWindows ()


waitTestWindows ();

Used within an automation script to pause until all windows previously created with createTestWindow have been mapped and exposed.


destroyTestWindows ()


destroyTestWindows ();

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.


defineScriptEvent ()


defineScriptEvent (string   name,
                   string   description);

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

Parameters

name

The event will be called script.

 

description

Short human-readable description of the event

 

scriptEvent ()


scriptEvent (string   name);

Convenience function to record a script-local performance event previously defined with defineScriptEvent

Parameters

name

Name registered with defineScriptEvent()

 

collectStatistics ()


collectStatistics ();

Convenience function to trigger statistics collection


runPerfScript ()


runPerfScript (scriptModule);

Runs a script for automated collection of performance data. The script is defined as a Javascript module with specified contents.

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.

Parameters

scriptModule

module object with run and finish functions and event handlers