testing.rst (10506B)
1 Testing 2 ======= 3 This documentation discusses how to write a test for the address bar and the 4 different test utilities that are useful when writing a test for the address 5 bar. 6 7 Common Tests 8 ------------ 9 Mochitests 10 ~~~~~~~~~~ 11 Some common tests for the address bar are the **mochitests**. The purpose of 12 a mochitest is to run the browser itself. Mochitests can be called 13 "browser tests", "mochitest-browser-chrome", or 14 "browser-chrome-mochitests". There are other types of mochitests that are not 15 for testing the browser and therefore can be ignored for the purpose of the 16 address bar. An example of a mochitest is 17 `tests/browser/browser_switchTab_currentTab.js <https://searchfox.org/mozilla- 18 central/source/browser/components/urlbar/tests/browser/browser_switchTab_ 19 currentTab.js>`_ 20 21 XPCShell 22 ~~~~~~~~ 23 `XPCShell Tests <https://firefox-source-docs.mozilla.org/testing/xpcshell/index 24 .html>`_ are another type of test relevant to the address bar. XPCShell tests 25 are often called unit tests because they tend to test specific modules or 26 components in isolation, as opposed the mochitest which have access to the full 27 browser chrome. 28 29 XPCShell tests do not use the browser UI and are completely separate from 30 browser chrome. XPCShell tests are executed in a JavaScript shell that is 31 outside of the browser. For historical context, the "XPC" naming convention is 32 from XPCOM (Cross Platform Component Model) which is an older framework that 33 allows programmers to write custom functions in one language, such as C++, and 34 connect it to other components in another language, such as JavaScript. 35 36 Each XPCShell test is executed in a new shell instance, therefore you will 37 see several Firefox icons pop up and close when XPCShell tests are executing. 38 These are two examples of XPCShell tests for the address bar 39 `test_providerHeuristicFallback <https://searchfox.org/mozilla-central/source 40 /browser/components/urlbar/tests/unit/test_providerHeuristicFallback.js>`_ 41 and 42 `test_providerTabToSearch <https://searchfox.org/mozilla-central/source/browser 43 /components/urlbar/tests/unit/test_providerTabToSearch.js>`_. 44 45 When To Write a XPCShell or Mochitest? 46 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 47 Always default to writing an XPCShell test if it is possible. XPCShell 48 tests are faster to execute than browser tests. Although, most of the time you 49 will write a browser test because you could be modifying something in the UI or 50 testing a specific component in the UI. 51 52 If you are writing a test for a urlbarProvider, you can test the Provider 53 through a XPCShell test. Providers do not modify the UI, instead what they do is 54 receive a url string query, search for the string and bring back the result. An 55 example is the `ProviderPlaces <https://searchfox.org/mozilla-central/sou 56 rce/browser/components/urlbar/UrlbarProviderPlaces.sys.mjs>`_, which fetches 57 results from the Places database. Another component that’s good for writing 58 XPCShell test is the `urlbarMuxer <https://searchfox.org/mozilla-central/ 59 source/browser/components/urlbar/UrlbarMuxerStandard.sys.mjs>`_. 60 61 There may be times where writing both an XPCShell test and browser test is 62 necessary. In these situations, you could be testing the result from a Provider 63 and also testing what appears in the UI is correct. 64 65 How To Write a Test 66 ------------------- 67 68 Test Boilerplate 69 ~~~~~~~~~~~~~~~~ 70 This basic test boilerplate includes a license code at the top and this license 71 code is present at the top of every test file, the ``"use strict"`` string is 72 to enable strict mode in JavaScript, and ``add_task`` function adds tests to be 73 executed by the test harness. 74 75 .. code-block:: javascript 76 77 /* Any copyright is dedicated to the Public Domain. 78 * http://creativecommons.org/publicdomain/zero/1.0/ */ 79 80 /** 81 * This tests ensures that the urlbar ... 82 */ 83 84 "use strict"; 85 86 add_task(async function testOne() { 87 // testing code and assertions 88 }); 89 90 add_task(async function testTwo() { 91 // testing code and assertions 92 }); 93 94 In order to run a test use the ``./mach`` command, for example, ``./mach test <path to test 95 file>`` to run test locally. Use the command with ``--jsdebugger`` argument at 96 the end to open the DevTools debugger to step through the test, ``./mach test 97 <path to test> --jsdebugger``. 98 99 Manifest 100 ~~~~~~~~ 101 The manifest's purpose is to list all the test in the directory and dictate to 102 the test harness which files are test and how the test harness should run these 103 test. Anytime a test is created, the test file name needs to be added to the 104 manifest in alphabetical order. 105 106 Start in the manifest file and add your test name in alphabetical 107 order. The manifest file we should add our test in is 108 `browser.toml <https://searchfox.org/mozilla-central/source/browser/components/ 109 urlbar/tests/browser/browser.toml>`_. The ``urlbar/test/browser/`` directory 110 is the main browser test directory for address bar, and the manifest file 111 linked above is the main browser test manifest. 112 113 Manifest Metadata 114 ~~~~~~~~~~~~~~~~~ 115 The manifest file can define common keys/metadata to influence the test's 116 behavior. For example, the metadata ``support-files`` are a list of additional 117 files required to run a test. Any values assigned to the key ``support-files`` 118 only applies to the single file directly above the ``support-files`` key. 119 If more files require ``support-files``, then ``support-files`` need to be 120 added directly under the other test file names. Another example of a manifest 121 metadata is ``[DEFAULT]``. Anything under ``[DEFAULT]`` will be picked up by 122 all tests in the manifest file. 123 124 For information on all the manifest metadata available, please visit 125 :doc:`/build/buildsystem/test_manifests`. 126 127 Common Test Utilities 128 --------------------- 129 This section describes common test utilities which may be useful when writing a 130 test for the address bar. Below are a description of common utils where you can 131 find helpful testing methods. 132 133 Many test utils modules end with ``TestUtils.sys.mjs``. However not every testing 134 function will end with ``TestUtils.sys.mjs``. For example, `PlacesUtils <https:// 135 searchfox.org/mozilla-central/source/toolkit/components/places/PlacesUtils. 136 sys.mjs>`_ does not have “Test” within its name. 137 138 A critical function to remember is the ``registerCleanupFunction`` within 139 the ``head.js`` file mentioned below. This function's purpose may be to clean 140 up the history or any other clean ups that are necessary after your test is 141 complete. Cleaning up after a browser test is necessary because clean up 142 ensures what is done within one test will not affect subsequent tests. 143 144 head.js and common-head.js 145 ~~~~~~~~~~~~~~~~~~~~~~~~~~ 146 The `head.js <https://searchfox.org/mozilla-central/source/browser/components 147 /urlbar/tests/browser/head.js>`_ file is executed at the beginning before each 148 test and contains imports to modules which are useful for each test. 149 Any tasks ``head.js`` adds (via add_task) will run first for each test, and 150 any variables and functions it defines will be available in the scope of 151 each test. This file is small because most of our Utils are actually in other 152 `.sys.mjs` files. 153 154 The ``ChromeUtils.defineESModuleGetters`` method within ``head.js`` sets up 155 modules names to where they can be found, their paths. ``Lazy`` means the files 156 are only imported if or when it is used. Any tests in this directory can use 157 these modules without importing it themselves in their own file. 158 The ``head.js`` provides a convenience for this purpose. The ``head.js`` file 159 imports `common-head.js <https://searchfox.org/mozilla-central/source/browser/components/urlbar/tests/browser/head-common.js>`_ 160 making everything within ``head-common.js`` available in ``head.js`` as well. 161 162 The ``registerCleanupFunction`` is an important function in browser mochi tests 163 and it is part of the test harness. This function registers a callback function 164 to be executed when your test is complete. The purpose may be to clean up the 165 history or any other clean ups that are necessary after your test is complete. 166 For example, browser mochi tests are executed one after the other in the same 167 window instance. The global object in each test is the browser ``window`` 168 object, for example, each test script runs in the browser window. 169 If the history is not cleaned up it will remain and may affect subsequent 170 browser tests. For most test outside of address bar, you may not need to clear 171 history. In addition to cleanup, ``head.js`` calls the 172 ``registerCleanupFunction`` to ensure the urlbar panel is closed after each 173 test. 174 175 UrlbarTestUtils 176 ~~~~~~~~~~~~~~~ 177 `UrlbarTestUtils.sys.mjs <https://searchfox.org/mozilla-central/source/browser/components/urlbar/tests/UrlbarTestUtils.sys.mjs>`_ is useful for url bar testing. This 178 file contains methods that can help with starting a new search in the url bar, 179 waiting for a new search to complete, returning the results in 180 the view, and etc. 181 182 BrowserTestUtils 183 ~~~~~~~~~~~~~~~~ 184 `BrowserTestUtils.sys.mjs <../../testing/browser-chrome/browsertestutils.html>`_ 185 is useful for browser window testing. This file contains methods that can help 186 with opening tabs, waiting for certain events to happen in the window, opening 187 new or private windows, and etc. 188 189 TestUtils 190 ~~~~~~~~~ 191 `TestUtils.sys.mjs <../../testing/testutils.html>`_ is useful for general 192 purpose testing and does not depend on the browser window. This file contains 193 methods that are useful when waiting for a condition to return true, waiting for 194 a specific preference to change, and etc. 195 196 PlacesTestUtils 197 ~~~~~~~~~~~~~~~ 198 :searchfox:`PlacesTestUtils.sys.mjs <toolkit/components/places/tests/PlacesTestUtils.sys.mjs>` is useful for adding visits, adding 199 bookmarks, waiting for notification of visited pages, and etc. 200 201 EventUtils 202 ~~~~~~~~~~ 203 `EventUtils.js <https://searchfox.org/mozilla-central/source/testing/mochitest 204 /tests/SimpleTest/EventUtils.js>`_ is an older test file and does not 205 need to be imported because it is not a ``.sys.mjs`` file. ``EventUtils`` is only 206 used for browser tests, unlike the other TestUtils listed above which are 207 used for browser tests, XPCShell tests and other tests. 208 209 All the functions within ``EventUtils.js`` are automatically available in 210 browser tests. This file contains functions that are useful for synthesizing 211 mouse clicks and keypresses. Some commonly used functions are 212 ``synthesizeMouseAtCenter`` which places the mouse at the center of the DOM 213 element and ``synthesizeKey`` which can be used to navigate the view and start 214 a search by using keydown and keyenter arguments.