dom/webidl/FuzzingFunctions.webidl

   1 /* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* This Source Code Form is subject to the terms of the Mozilla Public
   3  * License, v. 2.0. If a copy of the MPL was not distributed with this file,
   4  * You can obtain one at http://mozilla.org/MPL/2.0/.
   5  */
   6
   7 /*
   8  * Various functions useful for automated fuzzing that are enabled
   9  * only in --enable-fuzzing builds, because they may be dangerous to
  10  * enable on untrusted pages.
  11 */
  12
  13 [Pref="fuzzing.enabled",
  14  Exposed=Window]
  15 namespace FuzzingFunctions {
  16   /**
  17    * Synchronously perform a garbage collection.
  18    */
  19   undefined garbageCollect();
  20
  21   /**
  22    * Synchronously perform a compacting garbage collection.
  23    */
  24   undefined garbageCollectCompacting();
  25
  26   /**
  27    * Trigger a forced crash.
  28    */
  29   undefined crash(optional DOMString reason = "");
  30
  31   /**
  32    * Synchronously perform a cycle collection.
  33    */
  34   undefined cycleCollect();
  35
  36   /**
  37    * Send a memory pressure event, causes shrinking GC, cycle collection and
  38    * other actions.
  39    */
  40   undefined memoryPressure();
  41
  42   /**
  43    * Enable accessibility.
  44    */
  45   [Throws]
  46   undefined enableAccessibility();
  47
  48   /**
  49    * Send IPC fuzzing ready event to parent.
  50    */
  51   undefined signalIPCReady();
  52
  53   /**
  54    * synthesizeKeyboardEvents() synthesizes a set of "keydown",
  55    * "keypress" (only when it's necessary) and "keyup" events in top DOM window
  56    * in current process (and the synthesized events will be retargeted to
  57    * focused window/document/element).  I.e, this is currently not dispatched
  58    * via the main process if you call this in a content process.  Therefore, in
  59    * the case, some default action handlers which are only in the main process
  60    * will never run.  Note that this does not allow to synthesize keyboard
  61    * events if this is called from a keyboard event or composition event
  62    * listener.
  63    *
  64    * @param aKeyValue          If you want to synthesize non-printable key
  65    *                           events, you need to set one of key values
  66    *                           defined by "UI Events KeyboardEvent key Values".
  67    *                           You can check our current support values in
  68    *                           dom/events/KeyNameList.h
  69    *                           If you want to synthesize printable key events,
  70    *                           you can set any string value including empty
  71    *                           string.
  72    *                           Note that |key| value in aDictionary is always
  73    *                           ignored.
  74    * @param aDictionary        If you want to synthesize simple key press
  75    *                           without any modifiers, you can omit this.
  76    *                           Otherwise, specify this with proper values.
  77    *                           If |code| is omitted or empty string, this
  78    *                           guesses proper code value in US-English
  79    *                           keyboard.  Otherwise, the value must be empty
  80    *                           string or known code value defined by "UI Events
  81    *                           KeyboardEvent code Values".  You can check our
  82    *                           current support values in
  83    *                           dom/events/PhysicalKeyCodeNameList.h.
  84    *                           If |keyCode| is omitted or 0, this guesses
  85    *                           proper keyCode value in US-English keyboard.
  86    *                           If |location| is omitted or 0, this assumes
  87    *                           that left modifier key is pressed if aKeyValue
  88    *                           is one of such modifier keys.
  89    *                           |key|, |isComposing|, |charCode| and |which|
  90    *                           are always ignored.
  91    *                           Modifier states like |shiftKey|, |altKey|,
  92    *                           |modifierAltGraph|, |modifierCapsLock| and
  93    *                           |modifierNumLock| are not adjusted for
  94    *                           aKeyValue.  Please specify them manually if
  95    *                           necessary.
  96    *                           Note that this API does not allow to dispatch
  97    *                           known key events with empty |code| value and
  98    *                           0 |keyCode| value since it's unsual situation
  99    *                           especially 0 |keyCode| value with known key.
 100    *                           Note that when you specify only one of |code|
 101    *                           and |keyCode| value, the other will be guessed
 102    *                           from US-English keyboard layout.  So, if you
 103    *                           want to emulate key press with another keyboard
 104    *                           layout, you should specify both values.
 105    *
 106    * For example:
 107    *   // Synthesize "Tab" key events.
 108    *   synthesizeKeyboardEvents("Tab");
 109    *   // Synthesize Shift + Tab key events.
 110    *   synthesizeKeyboardEvents("Tab", { shiftKey: true });
 111    *   // Synthesize Control + A key events.
 112    *   synthesizeKeyboardEvents("a", { controlKey: true });
 113    *   // Synthesize Control + Shift + A key events.
 114    *   synthesizeKeyboardEvents("A", { controlKey: true,
 115    *                                   shitKey: true });
 116    *   // Synthesize "Enter" key on numpad.
 117    *   synthesizeKeyboardEvents("Enter", { code: "NumpadEnter" });
 118    *   // Synthesize right "Shift" key.
 119    *   synthesizeKeyboardEvents("Shift", { code: "ShiftRight" });
 120    *   // Synthesize "1" on numpad.
 121    *   synthesizeKeyboardEvents("1", { code: "Numpad1",
 122    *                                   modifierNumLock: true });
 123    *   // Synthesize "End" on numpad.
 124    *   synthesizeKeyboardEvents("End", { code: "Numpad1" });
 125    *   // Synthesize "%" key of US-English keyboard layout.
 126    *   synthesizeKeyboardEvents("%", { shiftKey: true });
 127    *   // Synthesize "*" key of Japanese keyboard layout.
 128    *   synthesizeKeyboardEvents("*", { code: "Quote",
 129    *                                   shiftKey: true,
 130    *                                   keyCode: KeyboardEvent.DOM_VK_COLON });
 131    */
 132   [Throws]
 133   undefined synthesizeKeyboardEvents(DOMString aKeyValue,
 134                                      optional KeyboardEventInit aDictionary = {});
 135 };