204 lines
9.7 KiB
Markdown
204 lines
9.7 KiB
Markdown
(urlbar-testing)=
|
||
|
||
# Address Bar Testing
|
||
|
||
This documentation discusses how to write a test for the address bar and the
|
||
different test utilities that are useful when writing a test for the address
|
||
bar.
|
||
|
||
## Common Tests
|
||
|
||
### Mochitests
|
||
|
||
Some common tests for the address bar are the **mochitests**. The purpose of
|
||
a mochitest is to run the browser itself. Mochitests can be called
|
||
"browser tests", "mochitest-browser-chrome", or
|
||
"browser-chrome-mochitests". There are other types of mochitests that are not
|
||
for testing the browser and therefore can be ignored for the purpose of the
|
||
address bar. An example of a mochitest is
|
||
[tests/browser/browser_switchTab_currentTab.js](https://searchfox.org/mozilla-central/source/browser/components/urlbar/tests/browser/browser_switchTab_currentTab.js)
|
||
|
||
### XPCShell
|
||
|
||
[XPCShell Tests](https://firefox-source-docs.mozilla.org/testing/xpcshell/index.html) are another type of test relevant to the address bar. XPCShell tests
|
||
are often called unit tests because they tend to test specific modules or
|
||
components in isolation, as opposed the mochitest which have access to the full
|
||
browser chrome.
|
||
|
||
XPCShell tests do not use the browser UI and are completely separate from
|
||
browser chrome. XPCShell tests are executed in a JavaScript shell that is
|
||
outside of the browser. For historical context, the "XPC" naming convention is
|
||
from XPCOM (Cross Platform Component Model) which is an older framework that
|
||
allows programmers to write custom functions in one language, such as C++, and
|
||
connect it to other components in another language, such as JavaScript.
|
||
|
||
Each XPCShell test is executed in a new shell instance, therefore you will
|
||
see several Firefox icons pop up and close when XPCShell tests are executing.
|
||
These are two examples of XPCShell tests for the address bar
|
||
{searchfox}`test_providerHeuristicFallback <browser/components/urlbar/tests/unit/test_providerHeuristicFallback.js>`
|
||
and
|
||
{searchfox}`test_providerTabToSearch <browser/components/urlbar/tests/unit/test_providerTabToSearch.js>`.
|
||
|
||
### When To Write a XPCShell or Mochitest?
|
||
|
||
Always default to writing an XPCShell test if it is possible. XPCShell
|
||
tests are faster to execute than browser tests. Although, most of the time you
|
||
will write a browser test because you could be modifying something in the UI or
|
||
testing a specific component in the UI.
|
||
|
||
If you are writing a test for a urlbarProvider, you can test the Provider
|
||
through a XPCShell test. Providers do not modify the UI, instead what they do is
|
||
receive a url string query, search for the string and bring back the result. An
|
||
example is the {searchfox}`ProviderPlaces <browser/components/urlbar/UrlbarProviderPlaces.sys.mjs>`, which fetches
|
||
results from the Places database. Another component that’s good for writing
|
||
XPCShell test is the {searchfox}`urlbarMuxer <browser/components/urlbar/UrlbarMuxerStandard.sys.mjs>`.
|
||
|
||
There may be times where writing both an XPCShell test and browser test is
|
||
necessary. In these situations, you could be testing the result from a Provider
|
||
and also testing what appears in the UI is correct.
|
||
|
||
## How To Write a Test
|
||
|
||
### Test Boilerplate
|
||
|
||
This basic test boilerplate includes a license code at the top and this license
|
||
code is present at the top of every test file, the `"use strict"` string is
|
||
to enable strict mode in JavaScript, and `add_task` function adds tests to be
|
||
executed by the test harness.
|
||
|
||
```javascript
|
||
/* Any copyright is dedicated to the Public Domain.
|
||
* http://creativecommons.org/publicdomain/zero/1.0/ */
|
||
|
||
/**
|
||
* This tests ensures that the urlbar ...
|
||
*/
|
||
|
||
"use strict";
|
||
|
||
add_task(async function testOne() {
|
||
// testing code and assertions
|
||
});
|
||
|
||
add_task(async function testTwo() {
|
||
// testing code and assertions
|
||
});
|
||
```
|
||
|
||
In order to run a test use the `./mach` command, for example, `./mach test <path to test
|
||
file>` to run test locally. Use the command with `--jsdebugger` argument at
|
||
the end to open the DevTools debugger to step through the test, `./mach test
|
||
<path to test> --jsdebugger`.
|
||
|
||
### Manifest
|
||
|
||
The manifest's purpose is to list all the test in the directory and dictate to
|
||
the test harness which files are test and how the test harness should run these
|
||
test. Anytime a test is created, the test file name needs to be added to the
|
||
manifest in alphabetical order.
|
||
|
||
Start in the manifest file and add your test name in alphabetical
|
||
order. The manifest file we should add our test in is
|
||
{searchfox}`browser.toml <browser/components/urlbar/tests/browser/browser.toml>`. The `urlbar/test/browser/` directory
|
||
is the main browser test directory for address bar, and the manifest file
|
||
linked above is the main browser test manifest.
|
||
|
||
### Manifest Metadata
|
||
|
||
The manifest file can define common keys/metadata to influence the test's
|
||
behavior. For example, the metadata `support-files` are a list of additional
|
||
files required to run a test. Any values assigned to the key `support-files`
|
||
only applies to the single file directly above the `support-files` key.
|
||
If more files require `support-files`, then `support-files` need to be
|
||
added directly under the other test file names. Another example of a manifest
|
||
metadata is `[DEFAULT]`. Anything under `[DEFAULT]` will be picked up by
|
||
all tests in the manifest file.
|
||
|
||
For information on all the manifest metadata available, please visit
|
||
{doc}`/build/buildsystem/test_manifests`.
|
||
|
||
## Common Test Utilities
|
||
|
||
This section describes common test utilities which may be useful when writing a
|
||
test for the address bar. Below are a description of common utils where you can
|
||
find helpful testing methods.
|
||
|
||
Many test utils modules end with `TestUtils.sys.mjs`. However not every testing
|
||
function will end with `TestUtils.sys.mjs`. For example, [PlacesUtils](https://searchfox.org/firefox-main/source/toolkit/components/places/PlacesUtils.sys.mjs) does not have “Test” within its name.
|
||
|
||
A critical function to remember is the `registerCleanupFunction` within
|
||
the `head.js` file mentioned below. This function's purpose may be to clean
|
||
up the history or any other clean ups that are necessary after your test is
|
||
complete. Cleaning up after a browser test is necessary because clean up
|
||
ensures what is done within one test will not affect subsequent tests.
|
||
|
||
### head.js and common-head.js
|
||
|
||
The {searchfox}`head.js <browser/components/urlbar/tests/browser/head.js>` file is executed at the beginning before each
|
||
test and contains imports to modules which are useful for each test.
|
||
Any tasks `head.js` adds (via add_task) will run first for each test, and
|
||
any variables and functions it defines will be available in the scope of
|
||
each test. This file is small because most of our Utils are actually in other
|
||
`.sys.mjs` files.
|
||
|
||
The `ChromeUtils.defineESModuleGetters` method within `head.js` sets up
|
||
modules names to where they can be found, their paths. `Lazy` means the files
|
||
are only imported if or when it is used. Any tests in this directory can use
|
||
these modules without importing it themselves in their own file.
|
||
The `head.js` provides a convenience for this purpose. The `head.js` file
|
||
imports {searchfox}`common-head.js <browser/components/urlbar/tests/browser/head-common.js>`
|
||
making everything within `head-common.js` available in `head.js` as well.
|
||
|
||
The `registerCleanupFunction` is an important function in browser mochi tests
|
||
and it is part of the test harness. This function registers a callback function
|
||
to be executed when your test is complete. The purpose may be to clean up the
|
||
history or any other clean ups that are necessary after your test is complete.
|
||
For example, browser mochi tests are executed one after the other in the same
|
||
window instance. The global object in each test is the browser `window`
|
||
object, for example, each test script runs in the browser window.
|
||
If the history is not cleaned up it will remain and may affect subsequent
|
||
browser tests. For most test outside of address bar, you may not need to clear
|
||
history. In addition to cleanup, `head.js` calls the
|
||
`registerCleanupFunction` to ensure the urlbar panel is closed after each
|
||
test.
|
||
|
||
### UrlbarTestUtils
|
||
|
||
{searchfox}`UrlbarTestUtils.sys.mjs <browser/components/urlbar/tests/UrlbarTestUtils.sys.mjs>` is useful for url bar testing. This
|
||
file contains methods that can help with starting a new search in the url bar,
|
||
waiting for a new search to complete, returning the results in
|
||
the view, and etc.
|
||
|
||
### BrowserTestUtils
|
||
|
||
[BrowserTestUtils.sys.mjs](../../testing/browser-chrome/browsertestutils.html)
|
||
is useful for browser window testing. This file contains methods that can help
|
||
with opening tabs, waiting for certain events to happen in the window, opening
|
||
new or private windows, and etc.
|
||
|
||
### TestUtils
|
||
|
||
[TestUtils.sys.mjs](../../testing/testutils.html) is useful for general
|
||
purpose testing and does not depend on the browser window. This file contains
|
||
methods that are useful when waiting for a condition to return true, waiting for
|
||
a specific preference to change, and etc.
|
||
|
||
### PlacesTestUtils
|
||
|
||
{searchfox}`PlacesTestUtils.sys.mjs <toolkit/components/places/tests/PlacesTestUtils.sys.mjs>` is useful for adding visits, adding
|
||
bookmarks, waiting for notification of visited pages, and etc.
|
||
|
||
### EventUtils
|
||
|
||
{searchfox}`EventUtils.js <testing/mochitest/tests/SimpleTest/EventUtils.js>` is an older test file and does not
|
||
need to be imported because it is not a `.sys.mjs` file. `EventUtils` is only
|
||
used for browser tests, unlike the other TestUtils listed above which are
|
||
used for browser tests, XPCShell tests and other tests.
|
||
|
||
All the functions within `EventUtils.js` are automatically available in
|
||
browser tests. This file contains functions that are useful for synthesizing
|
||
mouse clicks and keypresses. Some commonly used functions are
|
||
`synthesizeMouseAtCenter` which places the mouse at the center of the DOM
|
||
element and `synthesizeKey` which can be used to navigate the view and start
|
||
a search by using keydown and keyenter arguments.
|