From 26a029d407be480d791972afb5975cf62c9360a6 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Fri, 19 Apr 2024 02:47:55 +0200 Subject: Adding upstream version 124.0.1. Signed-off-by: Daniel Baumann --- testing/docs/chrome-tests/index.rst | 120 ++++++++++++++++++++++++++++++++++++ 1 file changed, 120 insertions(+) create mode 100644 testing/docs/chrome-tests/index.rst (limited to 'testing/docs/chrome-tests/index.rst') diff --git a/testing/docs/chrome-tests/index.rst b/testing/docs/chrome-tests/index.rst new file mode 100644 index 0000000000..5227c7228f --- /dev/null +++ b/testing/docs/chrome-tests/index.rst @@ -0,0 +1,120 @@ +Chrome Tests +============ + +.. _DISCLAIMER: + +**DISCLAIMER** +~~~~~~~~~~~~~~ + +**NOTE: Please use this document as a reference for existing chrome tests as you do not want to create new chrome tests. +If you're trying to test privileged browser code, write a browser mochitest instead; +if you are testing web platform code, use a wpt test, or a "plain" mochitest if you are unable to use a wpt test.** + +.. _Introduction: + +Introduction +~~~~~~~~~~~~ + +A chrome test is similar but not equivalent to a Mochitest running with chrome privileges. + +The chrome test suite is an automated testing framework designed to +allow testing of application chrome windows using JavaScript. +It allows you to run JavaScript code in the non-electroysis (e10s) content area +with chrome privileges, instead of directly in the browser window (as browser tests do instead). +These tests reports results using the same functions as the Mochitest test framework. +The chrome test suite depends on runtests.py from the Mochitest framework. + +.. _Running_the_chrome_tests: + +Running the chrome tests +~~~~~~~~~~~~~~~~~~~~~~~~ + +To run chrome tests, you need to `build +Firefox `__ with your +changes and find the test or test manifest you want to run. + +For example, to run all chrome tests under `toolkit/content`, run the following command: + +:: + + ./mach test toolkit/content/test/chrome/chrome.ini + +To run a single test, just pass the path to the test into mach: + +:: + + ./mach test toolkit/content/tests/chrome/test_largemenu.html + +You can also pass the path to a directory containing many tests. Run +`./mach test --help` for full documentation. + +.. _Writing_chrome_tests: + +Writing chrome tests +~~~~~~~~~~~~~~~~~~~~ + +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:: xml + + + + + + + Demo Test + + + + +

+ + 

+     
+   
+
+
+The comparison functions are identical to those supported by Mochitests,
+see how the comparison functions work
+in the Mochitest documentation for more details. The `EventUtils helper
+functions `__
+are available on the "EventUtils" object defined in the global scope.
+
+The test suite also supports asynchronous tests.
+To use these asynchronous tests, please use the `add_task() `__ functionality.
+
+Any exceptions thrown while running a test will be caught and reported
+in the test output as a failure. Exceptions thrown outside of the test's
+context (e.g. in a timeout, event handler, etc) will not be caught, but
+will result in a timed out test.
+
+The test file name must be prefixed with "test_", and must have a file
+extension of ".xhtml". Files that don't match this pattern will be ignored
+by the test harness, but you still can include them. For example, a XUL
+window file opened by your test_demo.xhtml via openDialog should be named
+window_demo.xhtml. Putting the bug number in the file name is recommended
+if your test verifies a bugfix, e.g. "test_bug123456.xhtml".
+
+Helper files can be included, for example, from
+``https://example.com/chrome/dom/workers/test/serviceworkers/serviceworkermanager_iframe.html``.
+
+.. _Adding_a_new_chrome_test_to_the_tree:
+
+Adding a new chrome test to the tree
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To add a new chrome test to the tree, please use `./mach test addtest the_test_directory/the_test_you_want_to_create.xhtml`.
+For more information about `addtest`, please run `./mach test addtest --help`.
-- 
cgit v1.2.3