File: scripting.js

package info (click to toggle)
cinnamon 3.2.7-4
  • links: PTS, VCS
  • area: main
  • in suites: stretch
  • size: 11,624 kB
  • sloc: ansic: 33,269; python: 18,048; xml: 1,504; makefile: 780; sh: 90; cpp: 54
file content (370 lines) | stat: -rw-r--r-- 12,517 bytes parent folder | download | duplicates (5)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
// -*- mode: js; js-indent-level: 4; indent-tabs-mode: nil -*-

const Gio = imports.gi.Gio;
const Mainloop = imports.mainloop;
const Meta = imports.gi.Meta;
const Cinnamon = imports.gi.Cinnamon;

const Main = imports.ui.main;

/**
 * FILE:scripting.js
 * @short_description: Scripts for driving cinnamon in an automated fasion
 *
 * 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.
 */

/**
 * sleep:
 * @milliseconds (int): number of milliseconds to wait
 *
 * 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);'
 */
function sleep(milliseconds) {
    let cb;

    Mainloop.timeout_add(milliseconds, function() {
                             if (cb)
                                 cb();
                             return false;
                         });

    return function(callback) {
        cb = callback;
    };
}

/**
 * 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();'
 */
function waitLeisure() {
    let cb;

    global.run_at_leisure(function() {
                             if (cb)
                                 cb();
                          });

    return function(callback) {
        cb = callback;
    };
}

const PerfHelperIface =
    '<node> \
        <interface name="org.Cinnamon.PerfHelper"> \
            <method name="CreateWindow"> \ <arg type="i" direction="in" /> \ <arg type="i" direction="in" /> \ <arg type="b" direction="in" /> \ <arg type="b" direction="in" /> \
            </method> \
            <method name="WaitWindows" /> \
            <method name="DestroyWindows" /> \
        </interface> \
    </node>';

var PerfHelperProxy = Gio.DBusProxy.makeProxyWrapper(PerfHelperIface);
function PerfHelper() {
    return new PerfHelperProxy(Gio.DBus.session, 'org.Cinnamon.PerfHelper', '/org/Cinnamon/PerfHelper');
}

let _perfHelper = null;
function _getPerfHelper() {
    if (_perfHelper == null)
        _perfHelper = new PerfHelper();

    return _perfHelper;
}

/**
 * createTestWindow:
 * @width (int): width of window, in pixels
 * @height (int): height of window, in pixels
 * @alpha (boolean): whether the window should be alpha transparent
 * @maximized (boolean): whethe the window should be created 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().
 */
function createTestWindow(width, height, alpha, maximized) {
    let cb;
    let perfHelper = _getPerfHelper();

    perfHelper.CreateWindowRemote(width, height, alpha, maximized,
                                  function(result, excp) {
                                      if (cb)
                                          cb();
                                  });

    return function(callback) {
        cb = callback;
    };
}

/**
 * waitTestWindows:
 *
 * Used within an automation script to pause until all windows previously
 * created with createTestWindow have been mapped and exposed.
 */
function waitTestWindows() {
    let cb;
    let perfHelper = _getPerfHelper();

    perfHelper.WaitWindowsRemote(function(result, excp) {
                                     if (cb)
                                         cb();
                                 });

    return function(callback) {
        cb = callback;
    };
}

/**
 * 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.
 */
function destroyTestWindows() {
    let cb;
    let perfHelper = _getPerfHelper();

    perfHelper.DestroyWindowsRemote(function(result, excp) {
                                        if (cb)
                                            cb();
                                    });

    return function(callback) {
        cb = callback;
    };
}

/**
 * defineScriptEvent
 * @name (string): The event will be called script.
 * @description (string): Short human-readable description of the event
 *
 * 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
 */
function defineScriptEvent(name, description) {
    Cinnamon.PerfLog.get_default().define_event("script." + name,
                                             description,
                                             "");
}

/**
 * scriptEvent
 * @name (string): Name registered with defineScriptEvent()
 *
 * Convenience function to record a script-local performance event
 * previously defined with defineScriptEvent
 */
function scriptEvent(name) {
    Cinnamon.PerfLog.get_default().event("script." + name);
}

/**
 * collectStatistics
 *
 * Convenience function to trigger statistics collection
 */
function collectStatistics() {
    Cinnamon.PerfLog.get_default().collect_statistics();
}

function _step(g, finish, onError) {
    try {
        let waitFunction = g.next();
        waitFunction(function() {
                         _step(g, finish, onError);
                     });
    } catch (err if err instanceof StopIteration) {
        if (finish)
            finish();
    } catch (err) {
        if (onError)
            onError(err);
    }
}

function _collect(scriptModule, outputFile) {
    let eventHandlers = {};

    for (let f in scriptModule) {
        let m = /([A-Za-z]+)_([A-Za-z]+)/.exec(f);
        if (m)
            eventHandlers[m[1] + "." + m[2]] = scriptModule[f];
    }

    Cinnamon.PerfLog.get_default().replay(
        function(time, eventName, signature, arg) {
            if (eventName in eventHandlers)
                eventHandlers[eventName](time, arg);
        });

    if ('finish' in scriptModule)
        scriptModule.finish();

    if (outputFile) {
        let f = Gio.file_new_for_path(outputFile);
        let raw = f.replace(null, false,
                            Gio.FileCreateFlags.NONE,
                            null);
        let out = Gio.BufferedOutputStream.new_sized (raw, 4096);
        Cinnamon.write_string_to_stream (out, "{\n");

        Cinnamon.write_string_to_stream(out, '"events":\n');
        Cinnamon.PerfLog.get_default().dump_events(out);

        let monitors = Main.layoutManager.monitors;
        let primary = Main.layoutManager.primaryIndex;
        Cinnamon.write_string_to_stream(out, ',\n"monitors":\n[');
        for (let i = 0; i < monitors.length; i++) {
            let monitor = monitors[i];
            if (i != 0)
                Cinnamon.write_string_to_stream(out, ', ');
            Cinnamon.write_string_to_stream(out, '"%s%dx%d+%d+%d"'.format(i == primary ? "*" : "",
                                                                       monitor.width, monitor.height,
                                                                       monitor.x, monitor.y));
        }
        Cinnamon.write_string_to_stream(out, ' ]');

        Cinnamon.write_string_to_stream(out, ',\n"metrics":\n[ ');
        let first = true;
        for (let name in scriptModule.METRICS) {
            let metric = scriptModule.METRICS[name];
            // Extra checks here because JSON.stringify generates
            // invalid JSON for undefined values
            if (metric.description == null) {
                log("Error: No description found for metric " + name);
                continue;
            }
            if (metric.units == null) {
                log("Error: No units found for metric " + name);
                continue;
            }
            if (metric.value == null) {
                log("Error: No value found for metric " + name);
                continue;
            }

            if (!first)
                Cinnamon.write_string_to_stream(out, ',\n  ');
            first = false;

            Cinnamon.write_string_to_stream(out,
                                         '{ "name": ' + JSON.stringify(name) + ',\n' +
                                         '    "description": ' + JSON.stringify(metric.description) + ',\n' +
                                         '    "units": ' + JSON.stringify(metric.units) + ',\n' +
                                         '    "value": ' + JSON.stringify(metric.value) + ' }');
        }
        Cinnamon.write_string_to_stream(out, ' ]');

        Cinnamon.write_string_to_stream (out, ',\n"log":\n');
        Cinnamon.PerfLog.get_default().dump_log(out);

        Cinnamon.write_string_to_stream (out, '\n}\n');
        out.close(null);
    } else {
        let metrics = [];
        for (let metric in scriptModule.METRICS)
            metrics.push(metric);

        metrics.sort();

        print ('------------------------------------------------------------');
        for (let i = 0; i < metrics.length; i++) {
            let metric = metrics[i];
            print ('# ' + scriptModule.METRIC_DESCRIPTIONS[metric]);
            print (metric + ': ' +  scriptModule.METRICS[metric]);
        }
        print ('------------------------------------------------------------');
    }
}

/**
 * runPerfScript:
 * @scriptModule: module object with run and finish functions
 *    and event handlers
 *
 * 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.
 */
function runPerfScript(scriptModule, outputFile) {
    Cinnamon.PerfLog.get_default().set_enabled(true);

    let g = scriptModule.run();

    _step(g,
          function() {
              _collect(scriptModule, outputFile);
              Meta.exit(Meta.ExitCode.SUCCESS);
          },
         function(err) {
             log("Script failed: " + err + "\n" + err.stack);
             Meta.exit(Meta.ExitCode.ERROR);
         });
}