index.rst (4501B)
1 Chrome Tests 2 ============ 3 4 .. _DISCLAIMER: 5 6 **DISCLAIMER** 7 ~~~~~~~~~~~~~~ 8 9 **NOTE: Please use this document as a reference for existing chrome tests as you do not want to create new chrome tests. 10 If you're trying to test privileged browser code, write a browser mochitest instead; 11 if you are testing web platform code, use a wpt test, or a "plain" mochitest if you are unable to use a wpt test.** 12 13 .. _Introduction: 14 15 Introduction 16 ~~~~~~~~~~~~ 17 18 A chrome test is similar but not equivalent to a Mochitest running with chrome privileges. 19 20 The chrome test suite is an automated testing framework designed to 21 allow testing of application chrome windows using JavaScript. 22 It allows you to run JavaScript code in the non-electroysis (e10s) content area 23 with chrome privileges, instead of directly in the browser window (as browser tests do instead). 24 These tests reports results using the same functions as the Mochitest test framework. 25 The chrome test suite depends on runtests.py from the Mochitest framework. 26 27 .. _Running_the_chrome_tests: 28 29 Running the chrome tests 30 ~~~~~~~~~~~~~~~~~~~~~~~~ 31 32 To run chrome tests, you need to `build 33 Firefox </setup>`__ with your 34 changes and find the test or test manifest you want to run. 35 36 For example, to run all chrome tests under `toolkit/content`, run the following command: 37 38 :: 39 40 ./mach test toolkit/content/test/chrome/chrome.toml 41 42 To run a single test, just pass the path to the test into mach: 43 44 :: 45 46 ./mach test toolkit/content/tests/chrome/test_largemenu.html 47 48 You can also pass the path to a directory containing many tests. Run 49 `./mach test --help` for full documentation. 50 51 .. _Writing_chrome_tests: 52 53 Writing chrome tests 54 ~~~~~~~~~~~~~~~~~~~~ 55 56 A chrome tests is similar but not equivalent to a Mochitest 57 running with chrome privileges, i.e. code and UI are referenced by 58 ``chrome://`` URIs. A basic XHTML test file could look like this: 59 60 .. code:: xml 61 62 <?xml version="1.0"?> 63 <?xml-stylesheet href="chrome://global/skin" type="text/css"?> 64 <?xml-stylesheet href="chrome://mochikit/content/tests/SimpleTest/test.css" type="text/css"?> 65 66 <window title="Demo Test" 67 xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul"> 68 <title>Demo Test</title> 69 70 <script type="application/javascript" 71 src="chrome://mochikit/content/tests/SimpleTest/SimpleTest.js"/> 72 73 <script type="application/javascript"> 74 <![CDATA[ 75 add_task(async function runTest() { 76 ok (true == 1, "this passes"); 77 todo(true === 1, "this fails"); 78 }); 79 ]]> 80 </script> 81 82 <body xmlns="http://www.w3.org/1999/xhtml"> 83 <p id="display"></p> 84 <div id="content" style="display: none"></div> 85 <pre id="test"></pre> 86 </body> 87 </window> 88 89 90 The comparison functions are identical to those supported by Mochitests, 91 see how the comparison functions work 92 in the Mochitest documentation for more details. The `EventUtils helper 93 functions <https://searchfox.org/mozilla-central/source/testing/mochitest/tests/SimpleTest/EventUtils.js>`__ 94 are available on the "EventUtils" object defined in the global scope. 95 96 The test suite also supports asynchronous tests. 97 To use these asynchronous tests, please use the `add_task() <https://searchfox.org/mozilla-central/source/testing/mochitest/tests/SimpleTest/SimpleTest.js#2025>`__ functionality. 98 99 Any exceptions thrown while running a test will be caught and reported 100 in the test output as a failure. Exceptions thrown outside of the test's 101 context (e.g. in a timeout, event handler, etc) will not be caught, but 102 will result in a timed out test. 103 104 The test file name must be prefixed with ``test_``, and must have a file 105 extension of ``.xhtml``. Files that don't match this pattern will be ignored 106 by the test harness, but you still can include them. For example, a XUL 107 window file opened by your test_demo.xhtml via openDialog should be named 108 window_demo.xhtml. Putting the bug number in the file name is recommended 109 if your test verifies a bugfix, e.g. "test_bug123456.xhtml". 110 111 Helper files can be included, for example, from 112 ``https://example.com/chrome/dom/workers/test/serviceworkers/serviceworkermanager_iframe.html``. 113 114 .. _Adding_a_new_chrome_test_to_the_tree: 115 116 Adding a new chrome test to the tree 117 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 118 119 To add a new chrome test to the tree, please use `./mach test addtest the_test_directory/the_test_you_want_to_create.xhtml`. 120 For more information about `addtest`, please run `./mach test addtest --help`.