## Scripting Scripting — Scripts for driving cinnamon in an automated fasion |

## Functions

| sleep ()
| waitLeisure ()
| createTestWindow ()
| waitTestWindows ()
| destroyTestWindows ()
| defineScriptEvent ()
| scriptEvent ()
| collectStatistics ()
| runPerfScript ()

## 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 |