mirror of
https://github.com/mozilla/gecko-dev.git
synced 2024-10-07 09:54:42 +00:00
Bug 1749473 - fix code blocks warnings r=firefox-source-docs-reviewers,sylvestre DONTBUILD
Depends on D167776 Differential Revision: https://phabricator.services.mozilla.com/D167777
This commit is contained in:
parent
892f701477
commit
88a7383fe0
@ -110,4 +110,4 @@ redirects:
|
||||
|
||||
fatal warnings:
|
||||
- "WARNING: '([^']*)' reference target not found:((?!.rst).)*$"
|
||||
max_num_warnings: 6639
|
||||
max_num_warnings: 6610
|
||||
|
@ -43,7 +43,7 @@ is available without any additional work).
|
||||
|
||||
Typical would be something like:
|
||||
|
||||
```lang=js
|
||||
```js
|
||||
add_task(async function() {
|
||||
await BrowserTestUtils.withNewTab("https://example.com/mypage", async (browser) {
|
||||
// `browser` will have finished loading the passed URL when this code runs.
|
||||
@ -57,7 +57,7 @@ add_task(async function() {
|
||||
|
||||
Should be done using `SpecialPowers.spawn`:
|
||||
|
||||
```lang=js
|
||||
```js
|
||||
let result = await SpecialPowers.spawn(browser, [42, 100], async (val, val2) => {
|
||||
// Replaces the document body with '42':
|
||||
content.document.body.textContent = val;
|
||||
@ -76,7 +76,7 @@ to the `window` of the web content in that browser/BrowsingContext.
|
||||
For some operations, like mouse clicks, convenience helpers are available on
|
||||
`BrowserTestUtils`:
|
||||
|
||||
```lang=js
|
||||
```js
|
||||
await BrowserTestUtils.synthesizeMouseAtCenter("#my.css.selector", {accelKey: true}, browser);
|
||||
```
|
||||
|
||||
@ -84,7 +84,7 @@ await BrowserTestUtils.synthesizeMouseAtCenter("#my.css.selector", {accelKey: tr
|
||||
|
||||
Use `SpecialPowers.pushPrefEnv`:
|
||||
|
||||
```lang=js
|
||||
```js
|
||||
await SpecialPowers.pushPrefEnv({
|
||||
set: [["accessibility.tabfocus", 7]]
|
||||
});
|
||||
@ -97,13 +97,13 @@ order for your test to pass reliably on macOS if it uses keyboard focus.
|
||||
|
||||
Use the utilities for this on [`TestUtils`](../testutils.html#TestUtils.topicObserved):
|
||||
|
||||
```lang=js
|
||||
```js
|
||||
await TestUtils.topicObserved("sync-pane-loaded");
|
||||
```
|
||||
|
||||
and [`BrowserTestUtils`](browsertestutils.html#BrowserTestUtils.waitForEvent), respectively:
|
||||
|
||||
```lang=js
|
||||
```js
|
||||
await BrowserTestUtils.waitForEvent(domElement, "click");
|
||||
```
|
||||
|
||||
@ -118,7 +118,7 @@ leads to intermittent failures.
|
||||
The [`Sinon`](https://sinonjs.org/) mocking framework is available. You can import it
|
||||
using something like:
|
||||
|
||||
```lang=js
|
||||
```js
|
||||
const { sinon } = ChromeUtils.import("resource://testing-common/Sinon.jsm");
|
||||
```
|
||||
|
||||
@ -129,7 +129,7 @@ More details on how to do mocking are available on the Sinon website.
|
||||
You can use extra files (e.g. webpages to load) by adding them to a `support-files`
|
||||
property using the `browser.ini` file:
|
||||
|
||||
```lang=ini
|
||||
```ini
|
||||
[browser_foo.js]
|
||||
support-files =
|
||||
bar.html
|
||||
|
@ -57,7 +57,7 @@ A chrome tests is similar but not equivalent to a Mochitest
|
||||
running with chrome privileges, i.e. code and UI are referenced by
|
||||
``chrome://`` URIs. A basic XHTML test file could look like this:
|
||||
|
||||
.. code:: eval
|
||||
.. code:: xml
|
||||
|
||||
<?xml version="1.0"?>
|
||||
<?xml-stylesheet href="chrome://global/skin" type="text/css"?>
|
||||
|
@ -34,7 +34,7 @@ subdocument.
|
||||
|
||||
For example, the following code pattern is bad:
|
||||
|
||||
.. code:: brush:
|
||||
.. code:: html
|
||||
|
||||
<html>
|
||||
<body>
|
||||
@ -50,7 +50,7 @@ For example, the following code pattern is bad:
|
||||
|
||||
Instead, write the code like this:
|
||||
|
||||
.. code:: brush:
|
||||
.. code:: html
|
||||
|
||||
<html>
|
||||
<body>
|
||||
@ -74,7 +74,7 @@ This may be relevant to event handlers, more than anything else. Let's
|
||||
say that you have an `<iframe>` and you want to
|
||||
do something after it's been loaded, so you might write code like this:
|
||||
|
||||
.. code:: brush:
|
||||
.. code:: html
|
||||
|
||||
<iframe src="..." onload="onLoad()"></iframe>
|
||||
<script>
|
||||
@ -92,7 +92,7 @@ may cause your test to time out, for example. The best way to fix this
|
||||
is to move the function definition before where it's used in the DOM,
|
||||
like this:
|
||||
|
||||
.. code:: brush:
|
||||
.. code:: html
|
||||
|
||||
<script>
|
||||
function onLoad() {
|
||||
@ -109,7 +109,7 @@ In general, when you have two asynchronous operations, you cannot assume
|
||||
any order between them. For example, let's say you have two
|
||||
`<iframe>`'s like this:
|
||||
|
||||
.. code:: brush:
|
||||
.. code:: html
|
||||
|
||||
<script>
|
||||
var f1Doc;
|
||||
@ -128,7 +128,7 @@ This code is implicitly assuming that ``f1`` will be loaded before
|
||||
detect when all of the asynchronous operations have been finished, and
|
||||
then do what you need to do, like this:
|
||||
|
||||
.. code:: brush:
|
||||
.. code:: html
|
||||
|
||||
<script>
|
||||
var f1Doc, loadCounter = 0;
|
||||
@ -155,7 +155,7 @@ tempting to use a timeout to wait a while, hoping that the operation has
|
||||
been finished by then and that it's then safe to continue. Such code
|
||||
uses patterns like this:
|
||||
|
||||
::
|
||||
.. code:: js
|
||||
|
||||
setTimeout(handler, 500);
|
||||
|
||||
@ -188,7 +188,7 @@ Using objects without accounting for the possibility of their death
|
||||
This is a very common pattern in our test suite, which was recently
|
||||
discovered to be responsible for many intermittent failures:
|
||||
|
||||
.. code:: brush:
|
||||
.. code:: js
|
||||
|
||||
function runLater(func) {
|
||||
var timer = Cc["@mozilla.org/timer;1"].createInstance(Ci.nsITimer);
|
||||
@ -204,7 +204,7 @@ this is to make the ``timer`` object global, so that an outstanding
|
||||
reference to the object would still exist by the time that the garbage
|
||||
collection code attempts to collect it.
|
||||
|
||||
.. code:: brush:
|
||||
.. code:: js
|
||||
|
||||
var timer;
|
||||
function runLater(func) {
|
||||
@ -240,7 +240,7 @@ test would fail intermittently on Linux. You can ensure that by using
|
||||
``SimpleTest.waitForFocus()`` and start what your test does from inside
|
||||
the callback for that function, as below:
|
||||
|
||||
::
|
||||
.. code:: js
|
||||
|
||||
SimpleTest.waitForFocus(function() {
|
||||
synthesizeKey("x", {});
|
||||
@ -326,7 +326,7 @@ intermittently. You can use the following pattern instead of calling
|
||||
``Math.random()`` if you need values that have to be unique for your
|
||||
test:
|
||||
|
||||
::
|
||||
.. code:: js
|
||||
|
||||
var gUniqueCounter = 0;
|
||||
function generateUniqueValues() {
|
||||
|
@ -38,7 +38,7 @@ Creating a new test in an existing directory
|
||||
If you're creating a new test in an existing directory, you can simply
|
||||
run:
|
||||
|
||||
.. code:: brush:
|
||||
.. code:: bash
|
||||
|
||||
$ ./mach addtest path/to/test/test_example.js
|
||||
$ hg add path/to/test/test_example.js
|
||||
@ -56,7 +56,7 @@ Running tests
|
||||
To run the test, execute it by running the ``mach`` command from the
|
||||
root of the Gecko source code directory.
|
||||
|
||||
::
|
||||
.. code:: bash
|
||||
|
||||
# Run a single test:
|
||||
$ ./mach xpcshell-test path/to/tests/test_example.js
|
||||
@ -327,7 +327,7 @@ When creating a new directory and new xpcshell.ini manifest file, the
|
||||
following must be added to a moz.build file near that file in the
|
||||
directory hierarchy:
|
||||
|
||||
::
|
||||
.. code:: bash
|
||||
|
||||
XPCSHELL_TESTS_MANIFESTS += ['path/to/xpcshell.ini']
|
||||
|
||||
@ -335,7 +335,7 @@ Typically, the moz.build containing *XPCSHELL_TESTS_MANIFESTS* is not in
|
||||
the same directory as *xpcshell.ini*, but rather in a parent directory.
|
||||
Common directory structures look like:
|
||||
|
||||
::
|
||||
.. code:: bash
|
||||
|
||||
feature
|
||||
├──moz.build
|
||||
@ -371,7 +371,7 @@ files can then be loaded in using the
|
||||
or other loaders. The support files can be located in other directory as
|
||||
well, and they will be made available by their filename.
|
||||
|
||||
::
|
||||
.. code:: bash
|
||||
|
||||
# File structure:
|
||||
|
||||
@ -382,7 +382,7 @@ well, and they will be made available by their filename.
|
||||
├──test_example.js
|
||||
└──xpcshell.ini
|
||||
|
||||
::
|
||||
.. code:: ini
|
||||
|
||||
# xpcshell.ini
|
||||
[DEFAULT]
|
||||
@ -392,7 +392,7 @@ well, and they will be made available by their filename.
|
||||
../../some/other/file.js
|
||||
[test_component_state.js]
|
||||
|
||||
.. code:: brush:
|
||||
.. code:: js
|
||||
|
||||
// head.js
|
||||
var globalValue = "A global value.";
|
||||
@ -401,7 +401,7 @@ well, and they will be made available by their filename.
|
||||
const { foo } = ChromeUtils.import("resource://test/module.jsm");
|
||||
const { bar } = ChromeUtils.import("resource://test/file.jsm");
|
||||
|
||||
.. code:: brush:
|
||||
.. code:: js
|
||||
|
||||
// test_example.js
|
||||
function run_test() {
|
||||
@ -425,7 +425,7 @@ The easiest is using the ``add_task`` helper. ``add_task`` can take an
|
||||
asynchronous function as a parameter. ``add_task`` tests are run
|
||||
automatically if you don't have a ``run_test`` function.
|
||||
|
||||
.. code:: brush:
|
||||
.. code:: js
|
||||
|
||||
add_task(async function test_foo() {
|
||||
let foo = await makeFoo(); // makeFoo() returns a Promise<foo>
|
||||
@ -446,7 +446,7 @@ list of asynchronously-run functions. Each function given to
|
||||
normally use ``add_task`` instead of ``add_test``, but you may see
|
||||
``add_test`` in existing tests.
|
||||
|
||||
.. code:: brush:
|
||||
.. code:: js
|
||||
|
||||
add_test(function test_foo() {
|
||||
makeFoo(function callback(foo) { // makeFoo invokes a callback<foo> once completed
|
||||
@ -472,7 +472,7 @@ our callbacks have been called and our test has completed. Newer tests
|
||||
prefer the use of ``add_task`` rather than this method. This can be
|
||||
achieved with ``do_test_pending()`` and ``do_test_finished()``:
|
||||
|
||||
.. code:: brush:
|
||||
.. code:: js
|
||||
|
||||
function run_test() {
|
||||
// Tell the harness to keep spinning the event loop at least
|
||||
@ -536,7 +536,7 @@ platforms. Use
|
||||
`AppConstants.jsm <https://searchfox.org/mozilla-central/rev/a0333927deabfe980094a14d0549b589f34cbe49/toolkit/modules/AppConstants.jsm#148>`__
|
||||
for determining the platform, for example:
|
||||
|
||||
.. code:: brush:
|
||||
.. code:: js
|
||||
|
||||
ChromeUtils.import("resource://gre/modules/AppConstants.jsm");
|
||||
|
||||
@ -563,7 +563,7 @@ skipped.
|
||||
For example, you can provide a test which only runs on Mac OS X like
|
||||
this:
|
||||
|
||||
::
|
||||
.. code:: js
|
||||
|
||||
ChromeUtils.import("resource://gre/modules/AppConstants.jsm");
|
||||
|
||||
@ -592,7 +592,7 @@ be skipped in certain configurations, or that a test is known to fail on
|
||||
certain platforms. You can do this in xpcshell manifests by adding
|
||||
annotations below the test file entry in the manifest, for example:
|
||||
|
||||
::
|
||||
.. code:: ini
|
||||
|
||||
[test_example.js]
|
||||
skip-if = os == 'win'
|
||||
@ -632,7 +632,7 @@ condition is true. If you add this to a test, make sure you file a bug
|
||||
on the failure and include the bug number in a comment in the manifest,
|
||||
like:
|
||||
|
||||
::
|
||||
.. code:: ini
|
||||
|
||||
[test_example.js]
|
||||
# bug xxxxxx
|
||||
@ -649,7 +649,7 @@ some cases where this is imperative, so we made this option available.
|
||||
If you add this to a test, make sure you specify a reason and possibly
|
||||
even a bug number, like:
|
||||
|
||||
::
|
||||
.. code:: ini
|
||||
|
||||
[test_example.js]
|
||||
run-sequentially = Has to launch Firefox binary, bug 123456.
|
||||
@ -670,7 +670,7 @@ When working on a specific feature or issue, it is convenient to only
|
||||
run a specific task from a whole test suite. Use ``.only()`` for that
|
||||
purpose:
|
||||
|
||||
.. code:: syntaxbox
|
||||
.. code:: js
|
||||
|
||||
add_task(async function some_test() {
|
||||
// Some test.
|
||||
@ -689,7 +689,7 @@ triggered. This sometimes causes issues during shutdown, when code is
|
||||
run that expects previously created events to have been already
|
||||
processed. In such cases, this code at the end of a test can help:
|
||||
|
||||
::
|
||||
.. code:: js
|
||||
|
||||
let thread = gThreadManager.currentThread;
|
||||
while (thread.hasPendingEvents())
|
||||
@ -772,7 +772,7 @@ is in your system PATH.
|
||||
|
||||
Example:
|
||||
|
||||
.. code:: eval
|
||||
.. code:: bash
|
||||
|
||||
$ ./mach xpcshell-test --debugger gdb --debugger-interactive netwerk/test/unit/test_resumable_channel.js
|
||||
# js>_execute_test();
|
||||
@ -781,19 +781,19 @@ Example:
|
||||
|
||||
On Windows with the VS debugger:
|
||||
|
||||
.. code:: eval
|
||||
.. code:: bash
|
||||
|
||||
$ ./mach xpcshell-test --debugger devenv --debugger-interactive netwerk/test/test_resumable_channel.js
|
||||
|
||||
Or with WinDBG:
|
||||
|
||||
.. code:: eval
|
||||
.. code:: bash
|
||||
|
||||
$ ./mach xpcshell-test --debugger windbg --debugger-interactive netwerk/test/test_resumable_channel.js
|
||||
|
||||
Or with modern WinDbg (WinDbg Preview as of April 2020):
|
||||
|
||||
.. code:: eval
|
||||
.. code:: bash
|
||||
|
||||
$ ./mach xpcshell-test --debugger WinDbgX --debugger-interactive netwerk/test/test_resumable_channel.js
|
||||
|
||||
@ -807,7 +807,7 @@ line) and run the test. You will see the child process emit a printf
|
||||
with its process ID, then sleep. Attach a debugger to the child's pid,
|
||||
and when it wakes up you can debug it:
|
||||
|
||||
::
|
||||
.. code:: bash
|
||||
|
||||
$ MOZ_DEBUG_CHILD_PROCESS=1 ./mach xpcshell-test test_simple_wrap.js
|
||||
CHILDCHILDCHILDCHILD
|
||||
|
Loading…
Reference in New Issue
Block a user