CINXE.COM

<!doctype html> <html class="writer-html5" lang="en" data-content_root="../../"> <head> <base href="https://firefox-source-docs.mozilla.org/testing/xpcshell/index.html"> <meta charset="utf-8"> <meta name="viewport" content="width=device-width, initial-scale=1"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <title>XPCShell tests — Firefox Source Docs documentation</title> <link rel="stylesheet" type="text/css" href="../../_static/pygments.css?v=fa44fd50"> <link rel="stylesheet" type="text/css" href="../../_static/css/theme.css?v=19f00094"> <link rel="stylesheet" type="text/css" href="../../_static/graphviz.css?v=fd3f3429"> <link rel="stylesheet" type="text/css" href="../../_static/copybutton.css?v=76b2166b"> <link rel="stylesheet" type="text/css" href="../../_static/custom_theme.css?v=dc5ed815"> <link rel="stylesheet" type="text/css" href="../../_static/design-style.1e8bd061cd6da7fc9cf755528e8ffc24.min.css?v=0a3b3ea7"> <link rel="shortcut icon" href="../../_static/firefox.ico"> <script src="../../_static/jquery.js?v=5d32c60e"></script> <script src="../../_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script> <script src="../../_static/documentation_options.js?v=5929fcd5"></script> <script src="../../_static/doctools.js?v=9a2dae69"></script> <script src="../../_static/sphinx_highlight.js?v=dc90522c"></script> <script src="../../_static/clipboard.min.js?v=a7894cd8"></script> <script src="../../_static/copybutton.js?v=30646c52"></script> <script src="../../_static/design-tabs.js?v=36754332"></script> <script src="../../_static/js/theme.js"></script> <link rel="index" title="Index" href="../../genindex.html"> <link rel="search" title="Search" href="../../search.html"> <link rel="next" title="TPS" href="../tps/index.html"> <link rel="prev" title="Mochitest" href="../mochitest-plain/index.html"> <meta http-equiv="X-Translated-By" content="Google"> <meta http-equiv="X-Translated-To" content="iw"> <script type="text/javascript" src="https://www.gstatic.com/_/translate_http/_/js/k=translate_http.tr.en_GB.tKc6KWkFf-8.O/am=gAE/d=1/rs=AN8SPfrf36LIV3DkhtRBGWFnLWWzaykPyw/m=corsproxy" data-sourceurl="https://firefox-source-docs.mozilla.org/testing/xpcshell/index.html"></script> <link href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:opsz,wght,FILL,GRAD@20..48,100..700,0..1,-50..200" rel="stylesheet"> <script type="text/javascript" src="https://www.gstatic.com/_/translate_http/_/js/k=translate_http.tr.en_GB.tKc6KWkFf-8.O/am=gAE/d=1/exm=corsproxy/ed=1/rs=AN8SPfrf36LIV3DkhtRBGWFnLWWzaykPyw/m=phishing_protection" data-phishing-protection-enabled="false" data-forms-warning-enabled="true" data-source-url="https://firefox-source-docs.mozilla.org/testing/xpcshell/index.html"></script> <meta name="robots" content="none"> </head> <body class="wy-body-for-nav"> <script type="text/javascript" src="https://www.gstatic.com/_/translate_http/_/js/k=translate_http.tr.en_GB.tKc6KWkFf-8.O/am=gAE/d=1/exm=corsproxy,phishing_protection/ed=1/rs=AN8SPfrf36LIV3DkhtRBGWFnLWWzaykPyw/m=navigationui" data-environment="prod" data-proxy-url="https://firefox--source--docs-mozilla-org.translate.goog" data-proxy-full-url="https://firefox--source--docs-mozilla-org.translate.goog/testing/xpcshell/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB" data-source-url="https://firefox-source-docs.mozilla.org/testing/xpcshell/index.html" data-source-language="pl" data-target-language="iw" data-display-language="en-GB" data-detected-source-language="" data-is-source-untranslated="false" data-source-untranslated-url="https://translate.google.com/website?sl=pl&tl=iw&hl=en-GB&u=https://firefox-source-docs.mozilla.org/testing/xpcshell/index.html&anno=2" data-client="tr"></script> <div class="wy-grid-for-nav"> <nav data-toggle="wy-nav-shift" class="wy-nav-side"> <div class="wy-side-scroll"> <div class="wy-side-nav-search"><a href="https://firefox--source--docs-mozilla-org.translate.goog/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB" class="icon icon-home"> Firefox Source Docs <img src="../../_static/firefox-wordmark.svg" class="logo" alt="Logo"> </a> <div> <h3>Quick search</h3> <script> (function () { var cx = "dd12886298f75dbef"; var gcse = document.createElement("script"); gcse.async = true; gcse.src = "https://cse.google.com/cse.js?cx=" + cx; var s = document.getElementsByTagName("script")[0]; s.parentNode.insertBefore(gcse, s); })(); </script><gcse:search></gcse:search> </div> </div> <div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu"> Overview <ul> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/glossary/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">A Glossary of Common Terms</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/overview/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">A Quick Guide to Mozilla Applications</a></li> </ul> Getting Started <ul> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/setup/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">Getting Set Up To Work On The Firefox Codebase</a></li> </ul> Working On Firefox <ul> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/contributing/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">Working on Firefox</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/bug-mgmt/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">Bug Handling</a></li> </ul> Firefox User Guide <ul> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/devtools-user/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">Firefox DevTools User Docs</a></li> </ul> Source Code Documentation <ul> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/mots/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">Governance</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/browser/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">Firefox Front-end</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/dom/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">DOM</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/editor/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">Editor</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/layout/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">Style system (CSS) & Layout</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/gfx/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">Graphics</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/ipc/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">Processes, Threads and IPC</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/devtools/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">Firefox DevTools Contributor Docs</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/toolkit/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">Toolkit</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/js/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">SpiderMonkey</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/jsloader/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">JS Loader</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/mobile/android/geckoview/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">GeckoView</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/mobile/android/fenix/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">Fenix</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/mobile/android/focus-android/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">Focus for Android</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/dom/bindings/webidl/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">WebIDL</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/modules/libpref/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">libpref</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/networking/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">Networking</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/remote/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">Remote Protocols</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/services/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">Services</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/permissions/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">Permissions</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/uriloader/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">File Handling</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/widget/cocoa/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">Firefox on macOS</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/widget/windows/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">Firefox on Windows</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/toolkit/components/ml/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">Firefox AI Runtime</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/accessible/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">Accessibility</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/media/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">Media Playback</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/code-quality/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">Code quality</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/writing-rust-code/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">Writing Rust Code</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/rust-components/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">Rust Components</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/tools/profiler/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">Gecko Profiler</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/performance/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">Performance</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/storage/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">Database bindings (SQLite, KV, …)</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/xpcom/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">XPCOM</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/nspr/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">NSPR</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/security/nss/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">Network Security Services (NSS)</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/content-security/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">Web Security Checks in Gecko</a></li> </ul> The Firefox Build System <ul> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/mach/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">Mach</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/tools/try/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">Pushing to Try</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/build/buildsystem/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">Build System</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/taskcluster/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">Firefox CI and Taskgraph</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/tools/moztreedocs/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">Managing Documentation</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/mozbuild/vendor/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">Vendoring Third Party Components</a></li> </ul> Testing & Test Infrastructure <ul class="current"> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/testing/automated-testing/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">Automated Testing</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/testing/treeherder-try/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">Understanding Treeherder Results</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/testing/sheriffed-intermittents/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">Sheriffed intermittent failures</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/testing/tests-for-new-config/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">Turning on Firefox tests for a new configuration</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/testing/intermittent/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">Avoiding intermittent tests</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/testing/testing-policy/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">Testing Policy</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/testing/ci-configs/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">Configuration Changes</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/testing/browser-chrome/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">Browser chrome mochitests</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/testing/chrome-tests/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">Chrome Tests</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/testing/marionette/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">Marionette</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/testing/geckodriver/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">geckodriver</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/testing/test-verification/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">Test Verification</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/testing/webrender/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">WebRender Tests</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/testing/mochitest-plain/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">Mochitest</a></li> <li class="toctree-l1 current"><a class="current reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/testing/xpcshell/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#">XPCShell tests</a> <ul> <li class="toctree-l2"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/testing/xpcshell/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#introducing-xpcshell-testing">Introducing xpcshell testing</a> <ul> <li class="toctree-l3"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/testing/xpcshell/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#creating-a-new-test-directory">Creating a new test directory</a></li> <li class="toctree-l3"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/testing/xpcshell/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#creating-a-new-test-in-an-existing-directory">Creating a new test in an existing directory</a></li> </ul></li> <li class="toctree-l2"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/testing/xpcshell/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#running-tests">Running tests</a></li> <li class="toctree-l2"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/testing/xpcshell/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#xpcshell-testing-api">xpcshell Testing API</a> <ul> <li class="toctree-l3"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/testing/xpcshell/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#assertions">Assertions</a></li> <li class="toctree-l3"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/testing/xpcshell/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#test-case-registration-and-execution">Test case registration and execution</a></li> <li class="toctree-l3"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/testing/xpcshell/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#environment">Environment</a></li> <li class="toctree-l3"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/testing/xpcshell/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#utility">Utility</a></li> <li class="toctree-l3"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/testing/xpcshell/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#multiprocess-communication">Multiprocess communication</a></li> </ul></li> <li class="toctree-l2"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/testing/xpcshell/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#xpcshell-toml-manifest">xpcshell.toml manifest</a> <ul> <li class="toctree-l3"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/testing/xpcshell/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#creating-a-new-xpcshell-toml-file">Creating a new xpcshell.toml file</a></li> <li class="toctree-l3"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/testing/xpcshell/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#test-head-and-support-files">Test head and support files</a></li> </ul></li> <li class="toctree-l2"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/testing/xpcshell/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#additional-testing-considerations">Additional testing considerations</a> <ul> <li class="toctree-l3"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/testing/xpcshell/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#async-tests">Async tests</a></li> </ul></li> <li class="toctree-l2"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/testing/xpcshell/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#task-based-asynchronous-tests">Task-based asynchronous tests</a> <ul> <li class="toctree-l3"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/testing/xpcshell/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#callback-based-asynchronous-tests">Callback-based asynchronous tests</a></li> <li class="toctree-l3"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/testing/xpcshell/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#other-tests">Other tests</a></li> <li class="toctree-l3"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/testing/xpcshell/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#testing-in-child-processeses">Testing in child processeses</a></li> <li class="toctree-l3"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/testing/xpcshell/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#platform-specific-tests">Platform-specific tests</a></li> <li class="toctree-l3"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/testing/xpcshell/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#runtime-detection">Runtime detection</a></li> </ul></li> <li class="toctree-l2"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/testing/xpcshell/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#conditionally-running-a-test">Conditionally running a test</a> <ul> <li class="toctree-l3"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/testing/xpcshell/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#adding-conditions-through-the-add-task-or-add-test-function">Adding conditions through the <code class="docutils literal notranslate">add_task</code> or <code class="docutils literal notranslate">add_test</code> function</a></li> <li class="toctree-l3"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/testing/xpcshell/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#adding-conditions-in-the-xpcshell-toml-manifest">Adding conditions in the xpcshell.toml manifest</a> <ul> <li class="toctree-l4"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/testing/xpcshell/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#skip-if">skip-if</a></li> <li class="toctree-l4"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/testing/xpcshell/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#fail-if">fail-if</a></li> <li class="toctree-l4"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/testing/xpcshell/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#run-sequentially">run-sequentially</a></li> </ul></li> <li class="toctree-l3"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/testing/xpcshell/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#manifest-conditional-expressions">Manifest conditional expressions</a></li> </ul></li> <li class="toctree-l2"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/testing/xpcshell/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#running-a-specific-test-only">Running a specific test only</a></li> <li class="toctree-l2"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/testing/xpcshell/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#problems-with-pending-events-and-shutdown">Problems with pending events and shutdown</a></li> <li class="toctree-l2"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/testing/xpcshell/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#debugging-xpcshell-tests">Debugging xpcshell-tests</a> <ul> <li class="toctree-l3"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/testing/xpcshell/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#running-unit-tests-under-the-javascript-debugger">Running unit tests under the javascript debugger</a></li> <li class="toctree-l3"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/testing/xpcshell/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#via-jsdebugger">Via –jsdebugger</a></li> </ul></li> <li class="toctree-l2"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/testing/xpcshell/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#running-unit-tests-under-a-c-debugger">Running unit tests under a C++ debugger</a> <ul> <li class="toctree-l3"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/testing/xpcshell/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#via-debugger-and-debugger-interactive">Via <code class="docutils literal notranslate">--debugger and -debugger-interactive</code></a></li> <li class="toctree-l3"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/testing/xpcshell/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#debugging-xpcshell-tests-in-a-child-process">Debugging xpcshell tests in a child process</a></li> <li class="toctree-l3"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/testing/xpcshell/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#debug-both-parent-and-child-processes">Debug both parent and child processes</a></li> </ul></li> </ul></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/testing/tps/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">TPS</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/web-platform/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">web-platform-tests</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/gtest/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">GTest</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/tools/fuzzing/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">Fuzzing</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/tools/sanitizer/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">Sanitizer</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/testing/perfdocs/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">Performance Testing</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/tools/code-coverage/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">Code coverage</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/testing-rust-code/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">Testing & Debugging Rust Code</a></li> </ul> Releases & Updates <ul> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/update-infrastructure/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">Mozilla Update Infrastructure</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/update-infrastructure/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#watershed-updates">Watershed Updates</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/update-infrastructure/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#desupport-updates">Desupport Updates</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/tools/update-verify/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">Update Verify</a></li> </ul> Localization & Internationalization <ul> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/intl/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">Internationalization</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/l10n/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">Localization</a></li> </ul> Firefox and Python <ul> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/mozbase/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">mozbase</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/python/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">Using third-party Python packages</a></li> </ul> Metrics Collected in Firefox <ul> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/metrics/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">Metrics</a></li> </ul> </div> </div> </nav> <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"> <nav class="wy-nav-top" aria-label="Mobile navigation menu"> <a href="https://firefox--source--docs-mozilla-org.translate.goog/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">Firefox Source Docs</a> </nav> <div class="wy-nav-content"> <div class="rst-content"> <div role="navigation" aria-label="Page navigation"> <ul class="wy-breadcrumbs"> <li><a href="https://firefox--source--docs-mozilla-org.translate.goog/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB" class="icon icon-home" aria-label="Home"></a></li> <li class="breadcrumb-item active">XPCShell tests</li> <li class="wy-breadcrumbs-aside"><a href="https://translate.google.com/website?sl=pl&tl=iw&hl=en-GB&u=https://bugzilla.mozilla.org/enter_bug.cgi?product%3DDeveloper%2BInfrastructure%26component%3DFirefox%2BSource%2BDocs%253A%2BContent%26short_desc%3DDocumentation%2Bissue%2Bon%2Btesting/xpcshell/index%26comment%3DURL%2B%3D%2Bhttps://firefox-source-docs.mozilla.org/testing/xpcshell/index.html%26bug_file_loc%3Dhttps://firefox-source-docs.mozilla.org/testing/xpcshell/index.html" rel="nofollow">Report an issue</a> / <a href="https://firefox--source--docs-mozilla-org.translate.goog/_sources/testing/xpcshell/index.rst.txt?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB" rel="nofollow"> View page source</a></li> </ul> <hr> </div> <div role="main" class="document" itemscope itemtype="http://schema.org/Article"> <div itemprop="articleBody"> <section id="xpcshell-tests"> <h1>XPCShell tests<a class="headerlink" href="https://firefox--source--docs-mozilla-org.translate.goog/testing/xpcshell/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#xpcshell-tests" title="Link to this heading"></a></h1> xpcshell tests are quick-to-run tests, that are generally used to write unit tests. They do not have access to the full browser chrome like <code class="docutils literal notranslate">browser chrome tests</code>, and so have much lower overhead. They are typical run by using <code class="docutils literal notranslate">./mach xpcshell-test</code> which initiates a new <code class="docutils literal notranslate">xpcshell</code> session with the xpcshell testing harness. Anything available to the XPCOM layer (through scriptable interfaces) can be tested with xpcshell. See <code class="docutils literal notranslate">Mozilla automated testing</code> and <code class="docutils literal notranslate">pages tagged "automated testing"</code> for more information. <section id="introducing-xpcshell-testing"> <h2>Introducing xpcshell testing<a class="headerlink" href="https://firefox--source--docs-mozilla-org.translate.goog/testing/xpcshell/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#introducing-xpcshell-testing" title="Link to this heading"></a></h2> xpcshell test filenames must start with <code class="docutils literal notranslate">test_</code>. <section id="creating-a-new-test-directory"> <h3>Creating a new test directory<a class="headerlink" href="https://firefox--source--docs-mozilla-org.translate.goog/testing/xpcshell/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#creating-a-new-test-directory" title="Link to this heading"></a></h3> If you need to create a new test directory, then follow the steps here. The test runner needs to know about the existence of the tests and how to configure them through the use of the <code class="docutils literal notranslate">xpcshell.toml</code> manifest file. First add a <code class="docutils literal notranslate">XPCSHELL_TESTS_MANIFESTS += ['xpcshell.toml']</code> declaration (with the correct relative <code class="docutils literal notranslate">xpcshell.toml</code> path) to the <code class="docutils literal notranslate">moz.build</code> file located in or above the directory. Then create an empty <code class="docutils literal notranslate">xpcshell.toml</code> file to tell the build system about the individual tests, and provide any additional configuration options. </section> <section id="creating-a-new-test-in-an-existing-directory"> <h3>Creating a new test in an existing directory<a class="headerlink" href="https://firefox--source--docs-mozilla-org.translate.goog/testing/xpcshell/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#creating-a-new-test-in-an-existing-directory" title="Link to this heading"></a></h3> If you’re creating a new test in an existing directory, you can simply run: <div class="highlight-bash notranslate"> <div class="highlight"> <pre>$ ./mach addtest path/to/test/test_example.js $ hg add path/to/test/test_example.js </pre> </div> </div> This will automatically create the test file and add it to <code class="docutils literal notranslate">xpcshell.toml</code>, the second line adds it to your commit. The test file contains an empty test which will give you an idea of how to write a test. There are plenty more examples throughout mozilla-central. </section> </section> <section id="running-tests"> <h2>Running tests<a class="headerlink" href="https://firefox--source--docs-mozilla-org.translate.goog/testing/xpcshell/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#running-tests" title="Link to this heading"></a></h2> To run the test, execute it by running the <code class="docutils literal notranslate">mach</code> command from the root of the Gecko source code directory. <div class="highlight-bash notranslate"> <div class="highlight"> <pre># Run a single test: $ ./mach xpcshell-test path/to/tests/test_example.js # Test an entire test suite in a folder: $ ./mach xpcshell-test path/to/tests/ # Or run any type of test, including both xpcshell and browser chrome tests: $ ./mach test path/to/tests/test_example.js </pre> </div> </div> The test is executed by the testing harness. It will call in turn: <ul class="simple"> <li><code class="docutils literal notranslate">run_test</code> (if it exists).</li> <li>Any functions added with <code class="docutils literal notranslate">add_task</code> or <code class="docutils literal notranslate">add_test</code> in the order they were defined in the file.</li> </ul> See also the notes below around <code class="docutils literal notranslate">add_task</code> and <code class="docutils literal notranslate">add_test</code>. </section> <section id="xpcshell-testing-api"> <h2>xpcshell Testing API<a class="headerlink" href="https://firefox--source--docs-mozilla-org.translate.goog/testing/xpcshell/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#xpcshell-testing-api" title="Link to this heading"></a></h2> xpcshell tests have access to the following functions. They are defined in <a class="reference external" href="https://translate.google.com/website?sl=pl&tl=iw&hl=en-GB&u=https://searchfox.org/mozilla-central/source/testing/xpcshell/head.js">testing/xpcshell/head.js</a> and <a class="reference external" href="https://translate.google.com/website?sl=pl&tl=iw&hl=en-GB&u=https://searchfox.org/mozilla-central/source/testing/modules/Assert.sys.mjs">testing/modules/Assert.sys.mjs</a>. <section id="assertions"> <h3>Assertions<a class="headerlink" href="https://firefox--source--docs-mozilla-org.translate.goog/testing/xpcshell/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#assertions" title="Link to this heading"></a></h3> <ul class="simple"> <li><code class="docutils literal notranslate">Assert.ok(truthyOrFalsy[, message])</code></li> <li><code class="docutils literal notranslate">Assert.equal(actual, expected[, message])</code></li> <li><code class="docutils literal notranslate">Assert.notEqual(actual, expected[, message])</code></li> <li><code class="docutils literal notranslate">Assert.deepEqual(actual, expected[, message])</code></li> <li><code class="docutils literal notranslate">Assert.notDeepEqual(actual, expected[, message])</code></li> <li><code class="docutils literal notranslate">Assert.strictEqual(actual, expected[, message])</code></li> <li><code class="docutils literal notranslate">Assert.notStrictEqual(actual, expected[, message])</code></li> <li><code class="docutils literal notranslate">Assert.rejects(actual, expected[, message])</code></li> <li><code class="docutils literal notranslate">Assert.greater(actual, expected[, message])</code></li> <li><code class="docutils literal notranslate">Assert.greaterOrEqual(actual, expected[, message])</code></li> <li><code class="docutils literal notranslate">Assert.less(actual, expected[, message])</code></li> <li><code class="docutils literal notranslate">Assert.lessOrEqual(actual, expected[, message])</code></li> </ul> These assertion methods are provided by <a class="reference external" href="https://translate.google.com/website?sl=pl&tl=iw&hl=en-GB&u=https://searchfox.org/mozilla-central/source/testing/modules/Assert.sys.mjs">testing/modules/Assert.sys.mjs</a>. It implements the <a class="reference external" href="https://translate.google.com/website?sl=pl&tl=iw&hl=en-GB&u=http://wiki.commonjs.org/wiki/Unit_Testing/1.1">CommonJS Unit Testing specification version 1.1</a>, which provides a basic, standardized interface for performing in-code logical assertions with optional, customizable error reporting. It is highly recommended to use these assertion methods, instead of the ones mentioned below. You can on all these methods remove the <code class="docutils literal notranslate">Assert.</code> from the beginning of the name, e.g. <code class="docutils literal notranslate">ok(true)</code> rather than <code class="docutils literal notranslate">Assert.ok(true)</code>, however keeping the <code class="docutils literal notranslate">Assert.</code> prefix may be seen as more descriptive and easier to spot where the tests are. <code class="docutils literal notranslate">Assert.throws(callback, expectedException[, message])</code> <code class="docutils literal notranslate">Assert.throws(callback[, message])</code> Asserts that the provided callback function throws an exception. The <code class="docutils literal notranslate">expectedException</code> argument can be an <code class="docutils literal notranslate">Error</code> instance, or a regular expression matching part of the error message (like in <code class="docutils literal notranslate">Assert.throws(() => a.b, /is not defined/</code>). <code class="docutils literal notranslate">Assert.rejects(promise, expectedException[, message])</code> Asserts that the provided promise is rejected. Note: that this should be called prefixed with an <code class="docutils literal notranslate">await</code>. The <code class="docutils literal notranslate">expectedException</code> argument can be an <code class="docutils literal notranslate">Error</code> instance, or a regular expression matching part of the error message. Example: <code class="docutils literal notranslate">await Assert.rejects(myPromise, /bad response/);</code> </section> <section id="test-case-registration-and-execution"> <h3>Test case registration and execution<a class="headerlink" href="https://firefox--source--docs-mozilla-org.translate.goog/testing/xpcshell/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#test-case-registration-and-execution" title="Link to this heading"></a></h3> <dl class="simple"> <dt> <code class="docutils literal notranslate">add_task([condition, ]testFunc)</code> </dt> <dd> Add an asynchronous function or to the list of tests that are to be run asynchronously. Whenever the function <code class="docutils literal notranslate">await</code>s a <a class="reference external" href="https://translate.google.com/website?sl=pl&tl=iw&hl=en-GB&u=https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a>, the test runner waits until the promise is resolved or rejected before proceeding. Rejected promises are converted into exceptions, and resolved promises are converted into values. You can optionally specify a condition which causes the test function to be skipped; see <a class="reference external" href="https://firefox--source--docs-mozilla-org.translate.goog/testing/xpcshell/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#adding-conditions-through-the-add-task-or-add-test-function">Adding conditions through the add_task or add_test function</a> for details. For tests that use <code class="docutils literal notranslate">add_task()</code>, the <code class="docutils literal notranslate">run_test()</code> function is optional, but if present, it should also call <code class="docutils literal notranslate">run_next_test()</code> to start execution of all asynchronous test functions. The test cases must not call <code class="docutils literal notranslate">run_next_test()</code>, it is called automatically when the task finishes. See <a class="reference external" href="https://firefox--source--docs-mozilla-org.translate.goog/testing/xpcshell/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#async-tests">Async tests</a>, below, for more information. </dd> <dt> <code class="docutils literal notranslate">add_test([condition, ]testFunction)</code> </dt> <dd> Add a test function to the list of tests that are to be run asynchronously. You can optionally specify a condition which causes the test function to be skipped; see <a class="reference external" href="https://firefox--source--docs-mozilla-org.translate.goog/testing/xpcshell/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#adding-conditions-through-the-add-task-or-add-test-function">Adding conditions through the add_task or add_test function</a> for details. Each test function must call <code class="docutils literal notranslate">run_next_test()</code> when it’s done. For tests that use <code class="docutils literal notranslate">add_test()</code>, <code class="docutils literal notranslate">the run_test()</code> function is optional, but if present, it should also call <code class="docutils literal notranslate">run_next_test()</code> to start execution of all asynchronous test functions. In most cases, you should rather use the more readable variant <code class="docutils literal notranslate">add_task()</code>. See <a class="reference external" href="https://firefox--source--docs-mozilla-org.translate.goog/testing/xpcshell/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#async-tests">Async tests</a>, below, for more information. </dd> <dt> <code class="docutils literal notranslate">run_next_test()</code> </dt> <dd> Run the next test function from the list of asynchronous tests. Each test function must call <code class="docutils literal notranslate">run_next_test()</code> when it’s done. <code class="docutils literal notranslate">run_test()</code> should also call <code class="docutils literal notranslate">run_next_test()</code> to start execution of all asynchronous test functions. See <a class="reference external" href="https://firefox--source--docs-mozilla-org.translate.goog/testing/xpcshell/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#async-tests">Async tests</a>, below, for more information. </dd> <dt> ``registerCleanupFunction``<code class="docutils literal notranslate">(callback)</code> </dt> <dd> Executes the function <code class="docutils literal notranslate">callback</code> after the current JS test file has finished running, regardless of whether the tests inside it pass or fail. You can use this to clean up anything that might otherwise cause problems between test runs. If <code class="docutils literal notranslate">callback</code> returns a <code class="docutils literal notranslate">Promise</code>, the test will not finish until the promise is fulfilled or rejected (making the termination function asynchronous). Cleanup functions are called in reverse order of registration. </dd> <dt> <code class="docutils literal notranslate">do_test_pending()</code> </dt> <dd> Delay exit of the test until do_test_finished() is called. do_test_pending() may be called multiple times, and do_test_finished() must be paired with each before the unit test will exit. </dd> <dt> <code class="docutils literal notranslate">do_test_finished()</code> </dt> <dd> Call this function to inform the test framework that an asynchronous operation has completed. If all asynchronous operations have completed (i.e., every do_test_pending() has been matched with a do_test_finished() in execution), then the unit test will exit. </dd> </dl> </section> <section id="environment"> <h3>Environment<a class="headerlink" href="https://firefox--source--docs-mozilla-org.translate.goog/testing/xpcshell/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#environment" title="Link to this heading"></a></h3> <dl> <dt> <code class="docutils literal notranslate">do_get_file(testdirRelativePath, allowNonexistent)</code> </dt> <dd> Returns an <code class="docutils literal notranslate">nsILocalFile</code> object representing the given file (or directory) in the test directory. For example, if your test is unit/test_something.js, and you need to access unit/data/somefile, you would call <code class="docutils literal notranslate">do_get_file('data/somefile')</code>. The given path must be delimited with forward slashes. You can use this to access test-specific auxiliary files if your test requires access to external files. Note that you can also use this function to get directories. <div class="admonition note"> Note Note: If your test needs access to one or more files that aren’t in the test directory, you should install those files to the test directory in the Makefile where you specify <code class="docutils literal notranslate">XPCSHELL_TESTS</code>. For an example, see <code class="docutils literal notranslate">netwerk/test/Makefile.in#117</code>. </div> </dd> <dt> <code class="docutils literal notranslate">do_get_profile()</code> </dt> <dd> Registers a directory with the profile service and returns an <code class="docutils literal notranslate">nsILocalFile</code> object representing that directory. It also makes sure that the profile-change-net-teardown, profile-change-teardown, and profile-before-change <a class="reference external" href="https://firefox--source--docs-mozilla-org.translate.goog/en/Observer_Notifications?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#Application_shutdown">observer notifications</a> are sent before the test finishes. This is useful if the components loaded in the test observe them to do cleanup on shutdown (e.g., places). <div class="admonition note"> Note Note: <code class="docutils literal notranslate">do_register_cleanup</code> will perform any cleanup operation before the profile and the network is shut down by the observer notifications. </div> </dd> <dt> <code class="docutils literal notranslate">do_get_idle()</code> </dt> <dd> By default xpcshell tests will disable the idle service, so that idle time will always be reported as 0. Calling this function will re-enable the service and return a handle to it; the idle time will then be correctly requested to the underlying OS. The idle-daily notification could be fired when requesting idle service. It is suggested to always get the service through this method if the test has to use idle. </dd> <dt> <code class="docutils literal notranslate">do_get_cwd()</code> </dt> <dd> Returns an <code class="docutils literal notranslate">nsILocalFile</code> object representing the test directory. This is the directory containing the test file when it is currently being run. Your test can write to this directory as well as read any files located alongside your test. Your test should be careful to ensure that it will not fail if a file it intends to write already exists, however. </dd> <dt> <code class="docutils literal notranslate">load(testdirRelativePath)</code> </dt> <dd> Imports the JavaScript file referenced by <code class="docutils literal notranslate">testdirRelativePath</code> into the global script context, executing the code inside it. The file specified is a file within the test directory. For example, if your test is unit/test_something.js and you have another file unit/extra_helpers.js, you can load the second file from the first by calling <code class="docutils literal notranslate">load('extra_helpers.js')</code>. </dd> </dl> </section> <section id="utility"> <h3>Utility<a class="headerlink" href="https://firefox--source--docs-mozilla-org.translate.goog/testing/xpcshell/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#utility" title="Link to this heading"></a></h3> <dl class="simple"> <dt> <code class="docutils literal notranslate">do_parse_document(path, type)</code> </dt> <dd> Parses and returns a DOM document. </dd> <dt> <code class="docutils literal notranslate">executeSoon(callback)</code> </dt> <dd> Executes the function <code class="docutils literal notranslate">callback</code> on a later pass through the event loop. Use this when you want some code to execute after the current function has finished executing, but you don’t care about a specific time delay. This function will automatically insert a <code class="docutils literal notranslate">do_test_pending</code> / <code class="docutils literal notranslate">do_test_finished</code> pair for you. </dd> <dt> <code class="docutils literal notranslate">do_timeout(delay, fun)</code> </dt> <dd> Call this function to schedule a timeout. The given function will be called with no arguments provided after the specified delay (in milliseconds). Note that you must call <code class="docutils literal notranslate">do_test_pending</code> so that the test isn’t completed before your timer fires, and you must call <code class="docutils literal notranslate">do_test_finished</code> when the actions you perform in the timeout complete, if you have no other functionality to test. (Note: the function argument used to be a string argument to be passed to eval, and some older branches support only a string argument or support both string and function.) </dd> </dl> </section> <section id="multiprocess-communication"> <h3>Multiprocess communication<a class="headerlink" href="https://firefox--source--docs-mozilla-org.translate.goog/testing/xpcshell/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#multiprocess-communication" title="Link to this heading"></a></h3> <dl class="simple"> <dt> <code class="docutils literal notranslate">do_send_remote_message(name, optionalData)</code> </dt> <dd> Asynchronously send a message to all remote processes. Pairs with <code class="docutils literal notranslate">do_await_remote_message</code> or equivalent ProcessMessageManager listeners. </dd> <dt> <code class="docutils literal notranslate">do_await_remote_message(name, optionalCallback)</code> </dt> <dd> Returns a promise that is resolved when the message is received. Must be paired with<code class="docutils literal notranslate">do_send_remote_message</code> or equivalent ProcessMessageManager calls. If optionalCallback is provided, the callback must call <code class="docutils literal notranslate">do_test_finished</code>. If optionalData is passed to <code class="docutils literal notranslate">do_send_remote_message</code> then that data is the first argument to optionalCallback or the value to which the promise resolves. </dd> </dl> </section> </section> <section id="xpcshell-toml-manifest"> <h2>xpcshell.toml manifest<a class="headerlink" href="https://firefox--source--docs-mozilla-org.translate.goog/testing/xpcshell/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#xpcshell-toml-manifest" title="Link to this heading"></a></h2> The manifest controls what tests are included in a test suite, and the configuration of the tests. It is loaded via the `moz.build` property configuration property. The following are all of the configuration options for a test suite as listed under the <code class="docutils literal notranslate">[DEFAULT]</code> section of the manifest. <dl class="simple"> <dt> <code class="docutils literal notranslate">tags</code> </dt> <dd> Tests can be filtered by tags when running multiple tests. The command for mach is <code class="docutils literal notranslate">./mach xpcshell-test --tag TAGNAME</code> </dd> <dt> <code class="docutils literal notranslate">head</code> </dt> <dd> The relative path to the head JavaScript file, which is run once before a test suite is run. The variables declared in the root scope are available as globals in the test files. See <a class="reference external" href="https://firefox--source--docs-mozilla-org.translate.goog/testing/xpcshell/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#test-head-and-support-files">Test head and support files</a> for more information and usage. </dd> <dt> <code class="docutils literal notranslate">firefox-appdir</code> </dt> <dd> Set this to “browser” if your tests need access to things in the browser/ directory (e.g. additional XPCOM services that live there) </dd> <dt> <code class="docutils literal notranslate">skip-if</code> <code class="docutils literal notranslate">run-if</code> <code class="docutils literal notranslate">fail-if</code> </dt> <dd> For this entire test suite, run the tests only if they meet certain conditions. See <a class="reference external" href="https://firefox--source--docs-mozilla-org.translate.goog/testing/xpcshell/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#adding-conditions-through-the-add-task-or-add-test-function">Adding conditions in the xpcshell.toml manifest</a> for how to use these properties. </dd> <dt> <code class="docutils literal notranslate">support-files</code> </dt> <dd> Make files available via the <code class="docutils literal notranslate">resource://test/[filename]</code> path to the tests. The path can be relative to other directories, but it will be served only with the filename. See <a class="reference external" href="https://firefox--source--docs-mozilla-org.translate.goog/testing/xpcshell/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#test-head-and-support-files">Test head and support files</a> for more information and usage. </dd> <dt> <code class="docutils literal notranslate">[test_*]</code> </dt> <dd> Test file names must start with <code class="docutils literal notranslate">test_</code> and are listed in square brackets </dd> </dl> <section id="creating-a-new-xpcshell-toml-file"> <h3>Creating a new xpcshell.toml file<a class="headerlink" href="https://firefox--source--docs-mozilla-org.translate.goog/testing/xpcshell/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#creating-a-new-xpcshell-toml-file" title="Link to this heading"></a></h3> When creating a new directory and new xpcshell.toml manifest file, the following must be added to a moz.build file near that file in the directory hierarchy: <div class="highlight-bash notranslate"> <div class="highlight"> <pre>XPCSHELL_TESTS_MANIFESTS += ['path/to/xpcshell.toml'] </pre> </div> </div> Typically, the moz.build containing XPCSHELL_TESTS_MANIFESTS is not in the same directory as xpcshell.toml, but rather in a parent directory. Common directory structures look like: <div class="highlight-bash notranslate"> <div class="highlight"> <pre>feature ├──moz.build └──tests/xpcshell └──xpcshell.toml # or feature ├──moz.build └──tests ├──moz.build └──xpcshell └──xpcshell.toml </pre> </div> </div> </section> <section id="test-head-and-support-files"> <h3>Test head and support files<a class="headerlink" href="https://firefox--source--docs-mozilla-org.translate.goog/testing/xpcshell/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#test-head-and-support-files" title="Link to this heading"></a></h3> Typically in a test suite, similar setup code and dependencies will need to be loaded in across each test. This can be done through the test head, which is the file declared in the <code class="docutils literal notranslate">xpcshell.toml</code> manifest file under the <code class="docutils literal notranslate">head</code> property. The file itself is typically called <code class="docutils literal notranslate">head.js</code>. Any variable declared in the test head will be in the global scope of each test in that test suite. In addition to the test head, other support files can be declared in the <code class="docutils literal notranslate">xpcshell.toml</code> manifest file. This is done through the <code class="docutils literal notranslate">support-files</code> declaration. These files will be made available through the url <code class="docutils literal notranslate">resource://test</code> plus the name of the file. These files can then be loaded in using the <code class="docutils literal notranslate">ChromeUtils.importESModule</code> function or other loaders. The support files can be located in other directory as well, and they will be made available by their filename. <div class="highlight-bash notranslate"> <div class="highlight"> <pre># File structure: path/to/tests ├──head.js ├──module.mjs ├──moz.build ├──test_example.js └──xpcshell.toml </pre> </div> </div> <div class="highlight-toml notranslate"> <div class="highlight"> <pre># xpcshell.toml [DEFAULT] head = head.js support-files = ./module.mjs ../../some/other/file.js [test_component_state.js] </pre> </div> </div> <div class="highlight-js notranslate"> <div class="highlight"> <pre>// head.js var globalValue = "A global value."; // Import support-files. const { foo } = ChromeUtils.importESModule("resource://test/module.mjs"); const { bar } = ChromeUtils.importESModule("resource://test/file.mjs"); </pre> </div> </div> <div class="highlight-js notranslate"> <div class="highlight"> <pre>// test_example.js function run_test() { equal(globalValue, "A global value.", "Declarations in head.js can be accessed"); } </pre> </div> </div> </section> </section> <section id="additional-testing-considerations"> <h2>Additional testing considerations<a class="headerlink" href="https://firefox--source--docs-mozilla-org.translate.goog/testing/xpcshell/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#additional-testing-considerations" title="Link to this heading"></a></h2> <section id="async-tests"> <h3>Async tests<a class="headerlink" href="https://firefox--source--docs-mozilla-org.translate.goog/testing/xpcshell/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#async-tests" title="Link to this heading"></a></h3> Asynchronous tests (that is, those whose success cannot be determined until after <code class="docutils literal notranslate">run_test</code> finishes) can be written in a variety of ways. </section> </section> <section id="task-based-asynchronous-tests"> <h2>Task-based asynchronous tests<a class="headerlink" href="https://firefox--source--docs-mozilla-org.translate.goog/testing/xpcshell/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#task-based-asynchronous-tests" title="Link to this heading"></a></h2> The easiest is using the <code class="docutils literal notranslate">add_task</code> helper. <code class="docutils literal notranslate">add_task</code> can take an asynchronous function as a parameter. <code class="docutils literal notranslate">add_task</code> tests are run automatically if you don’t have a <code class="docutils literal notranslate">run_test</code> function. <div class="highlight-js notranslate"> <div class="highlight"> <pre>add_task(async function test_foo() { let foo = await makeFoo(); // makeFoo() returns a Promise<foo> equal(foo, expectedFoo, "Should have received the expected object"); }); add_task(async function test_bar() { let foo = await makeBar(); // makeBar() returns a Promise<bar> Assert.equal(bar, expectedBar, "Should have received the expected object"); }); </pre> </div> </div> <section id="callback-based-asynchronous-tests"> <h3>Callback-based asynchronous tests<a class="headerlink" href="https://firefox--source--docs-mozilla-org.translate.goog/testing/xpcshell/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#callback-based-asynchronous-tests" title="Link to this heading"></a></h3> You can also use <code class="docutils literal notranslate">add_test</code>, which takes a function and adds it to the list of asynchronously-run functions. Each function given to <code class="docutils literal notranslate">add_test</code> must also call <code class="docutils literal notranslate">run_next_test</code> at its end. You should normally use <code class="docutils literal notranslate">add_task</code> instead of <code class="docutils literal notranslate">add_test</code>, but you may see <code class="docutils literal notranslate">add_test</code> in existing tests. <div class="highlight-js notranslate"> <div class="highlight"> <pre>add_test(function test_foo() { makeFoo(function callback(foo) { // makeFoo invokes a callback<foo> once completed equal(foo, expectedFoo); run_next_test(); }); }); add_test(function test_bar() { makeBar(function callback(bar) { equal(bar, expectedBar); run_next_test(); }); }); </pre> </div> </div> </section> <section id="other-tests"> <h3>Other tests<a class="headerlink" href="https://firefox--source--docs-mozilla-org.translate.goog/testing/xpcshell/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#other-tests" title="Link to this heading"></a></h3> We can also tell the test harness not to kill the test process once <code class="docutils literal notranslate">run_test()</code> is finished, but to keep spinning the event loop until our callbacks have been called and our test has completed. Newer tests prefer the use of <code class="docutils literal notranslate">add_task</code> rather than this method. This can be achieved with <code class="docutils literal notranslate">do_test_pending()</code> and <code class="docutils literal notranslate">do_test_finished()</code>: <div class="highlight-js notranslate"> <div class="highlight"> <pre>function run_test() { // Tell the harness to keep spinning the event loop at least // until the next do_test_finished() call. do_test_pending(); someAsyncProcess(function callback(result) { equal(result, expectedResult); // Close previous do_test_pending() call. do_test_finished(); }); } </pre> </div> </div> </section> <section id="testing-in-child-processeses"> <h3>Testing in child processeses<a class="headerlink" href="https://firefox--source--docs-mozilla-org.translate.goog/testing/xpcshell/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#testing-in-child-processeses" title="Link to this heading"></a></h3> By default xpcshell tests run in the parent process. If you wish to run test logic in the child, you have several ways to do it: <ol class="arabic simple"> <li>Create a regular test_foo.js test, and then write a wrapper test_foo_wrap.js file that uses the <code class="docutils literal notranslate">run_test_in_child()</code> function to run an entire script file in the child. This is an easy way to arrange for a test to be run twice, once in chrome and then later (via the _wrap.js file) in content. See /network/test/unit_ipc for examples. The <code class="docutils literal notranslate">run_test_in_child()</code> function takes a callback, so you should be able to call it multiple times with different files, if that’s useful.</li> <li>For tests that need to run logic in both the parent + child processes during a single test run, you may use the poorly documented <code class="docutils literal notranslate">sendCommand()</code> function, which takes a code string to be executed on the child, and a callback function to be run on the parent when it has completed. You will want to first call do_load_child_test_harness() to set up a reasonable test environment on the child. <code class="docutils literal notranslate">sendCommand</code> returns immediately, so you will generally want to use <code class="docutils literal notranslate">do_test_pending</code>/<code class="docutils literal notranslate">do_test_finished</code> with it. NOTE: this method of test has not been used much, and your level of pain may be significant. Consider option #1 if possible.</li> </ol> See the documentation for <code class="docutils literal notranslate">run_test_in_child()</code> and <code class="docutils literal notranslate">do_load_child_test_harness()</code> in testing/xpcshell/head.js for more information. </section> <section id="platform-specific-tests"> <h3>Platform-specific tests<a class="headerlink" href="https://firefox--source--docs-mozilla-org.translate.goog/testing/xpcshell/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#platform-specific-tests" title="Link to this heading"></a></h3> Sometimes you might want a test to know what platform it’s running on (to test platform-specific features, or allow different behaviors). Unit tests are not normally invoked from a Makefile (unlike Mochitests), or preprocessed (so not #ifdefs), so platform detection with those methods isn’t trivial. </section> <section id="runtime-detection"> <h3>Runtime detection<a class="headerlink" href="https://firefox--source--docs-mozilla-org.translate.goog/testing/xpcshell/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#runtime-detection" title="Link to this heading"></a></h3> Some tests will want to only execute certain portions on specific platforms. Use <a class="reference external" href="https://translate.google.com/website?sl=pl&tl=iw&hl=en-GB&u=https://searchfox.org/mozilla-central/rev/5f0a7ca8968ac5cef8846e1d970ef178b8b76dcc/toolkit/modules/AppConstants.sys.mjs%23158">AppConstants.sys.mjs</a> for determining the platform, for example: <div class="highlight-js notranslate"> <div class="highlight"> <pre>let { AppConstants } = ChromeUtils.importESModule("resource://gre/modules/AppConstants.mjs"); let isMac = AppConstants.platform == "macosx"; </pre> </div> </div> </section> </section> <section id="conditionally-running-a-test"> <h2>Conditionally running a test<a class="headerlink" href="https://firefox--source--docs-mozilla-org.translate.goog/testing/xpcshell/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#conditionally-running-a-test" title="Link to this heading"></a></h2> There are two different ways to conditional skip a test, either through <section id="adding-conditions-through-the-add-task-or-add-test-function"> <h3>Adding conditions through the <code class="docutils literal notranslate">add_task</code> or <code class="docutils literal notranslate">add_test</code> function<a class="headerlink" href="https://firefox--source--docs-mozilla-org.translate.goog/testing/xpcshell/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#adding-conditions-through-the-add-task-or-add-test-function" title="Link to this heading"></a></h3> You can use conditionals on individual test functions instead of entire files. The condition is provided as an optional first parameter passed into <code class="docutils literal notranslate">add_task()</code> or <code class="docutils literal notranslate">add_test()</code>. The condition is an object which contains a function named <code class="docutils literal notranslate">skip_if()</code>, which is an <a class="reference external" href="https://firefox--source--docs-mozilla-org.translate.goog/en-US/docs/Web/JavaScript/Reference/Functions/Arrow_functions?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">arrow function</a> returning a boolean value which is ``true`` if the test should be skipped. For example, you can provide a test which only runs on Mac OS X like this: <div class="highlight-js notranslate"> <div class="highlight"> <pre>let { AppConstants } = ChromeUtils.importESModule("resource://gre/modules/AppConstants.sys.mjs"); add_task({ skip_if: () => AppConstants.platform != "mac" }, async function some_test() { // Test code goes here }); </pre> </div> </div> Since <code class="docutils literal notranslate">AppConstants.platform != "mac"</code> is <code class="docutils literal notranslate">true</code> only when testing on Mac OS X, the test will be skipped on all other platforms. <div class="admonition note"> Note Note: Arrow functions are ideal here because if your condition compares constants, it will already have been evaluated before the test is even run, meaning your output will not be able to show the specifics of what the condition is. </div> </section> <section id="adding-conditions-in-the-xpcshell-toml-manifest"> <h3>Adding conditions in the xpcshell.toml manifest<a class="headerlink" href="https://firefox--source--docs-mozilla-org.translate.goog/testing/xpcshell/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#adding-conditions-in-the-xpcshell-toml-manifest" title="Link to this heading"></a></h3> Sometimes you may want to add conditions to specify that a test should 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: <div class="highlight-ini notranslate"> <div class="highlight"> <pre>[test_example.js] skip-if = os == 'win' </pre> </div> </div> This example would skip running <code class="docutils literal notranslate">test_example.js</code> on Windows. <div class="admonition note"> Note Note: Starting with Gecko (Firefox 40 / Thunderbird 40 / SeaMonkey 2.37), you can use conditionals on individual test functions instead of on entire files. See <a class="reference external" href="https://firefox--source--docs-mozilla-org.translate.goog/testing/xpcshell/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#adding-conditions-through-the-add-task-or-add-test-function">Adding conditions through the add_task or add_test function</a> above for details. </div> There are currently four conditionals you can specify: <section id="skip-if"> <h4>skip-if<a class="headerlink" href="https://firefox--source--docs-mozilla-org.translate.goog/testing/xpcshell/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#skip-if" title="Link to this heading"></a></h4> <code class="docutils literal notranslate">skip-if</code> tells the harness to skip running this test if the condition evaluates to true. You should use this only if the test has no meaning on a certain platform, or causes undue problems like hanging the test suite for a long time. <section id="run-if"> <h5>run-if<a class="headerlink" href="https://firefox--source--docs-mozilla-org.translate.goog/testing/xpcshell/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#run-if" title="Link to this heading"></a></h5> <code class="docutils literal notranslate">run-if</code> tells the harness to only run this test if the condition evaluates to true. It functions as the inverse of <code class="docutils literal notranslate">skip-if</code>. </section> </section> <section id="fail-if"> <h4>fail-if<a class="headerlink" href="https://firefox--source--docs-mozilla-org.translate.goog/testing/xpcshell/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#fail-if" title="Link to this heading"></a></h4> <code class="docutils literal notranslate">fail-if</code> tells the harness that this test is expected to fail if the 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: <div class="highlight-ini notranslate"> <div class="highlight"> <pre>[test_example.js] # bug xxxxxx fail-if = os == 'linux' </pre> </div> </div> </section> <section id="run-sequentially"> <h4>run-sequentially<a class="headerlink" href="https://firefox--source--docs-mozilla-org.translate.goog/testing/xpcshell/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#run-sequentially" title="Link to this heading"></a></h4> <code class="docutils literal notranslate">run-sequentially</code>basically tells the harness to run the respective test in isolation. This is required for tests that are not “thread-safe”. You should do all you can to avoid using this option, since this will kill performance. However, we understand that there are 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: <div class="highlight-ini notranslate"> <div class="highlight"> <pre>[test_example.js] run-sequentially = Has to launch Firefox binary, bug 123456. </pre> </div> </div> </section> </section> <section id="manifest-conditional-expressions"> <h3>Manifest conditional expressions<a class="headerlink" href="https://firefox--source--docs-mozilla-org.translate.goog/testing/xpcshell/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#manifest-conditional-expressions" title="Link to this heading"></a></h3> For a more detailed description of the syntax of the conditional expressions, as well as what variables are available, <cite>see this page </en/XPCshell_Test_Manifest_Expressions</cite>. </section> </section> <section id="running-a-specific-test-only"> <h2>Running a specific test only<a class="headerlink" href="https://firefox--source--docs-mozilla-org.translate.goog/testing/xpcshell/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#running-a-specific-test-only" title="Link to this heading"></a></h2> When working on a specific feature or issue, it is convenient to only run a specific task from a whole test suite. Use <code class="docutils literal notranslate">.only()</code> for that purpose: <div class="highlight-js notranslate"> <div class="highlight"> <pre>add_task(async function some_test() { // Some test. }); add_task(async function some_interesting_test() { // Only this test will be executed. }).only(); </pre> </div> </div> </section> <section id="problems-with-pending-events-and-shutdown"> <h2>Problems with pending events and shutdown<a class="headerlink" href="https://firefox--source--docs-mozilla-org.translate.goog/testing/xpcshell/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#problems-with-pending-events-and-shutdown" title="Link to this heading"></a></h2> Events are not processed during test execution if not explicitly 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: <div class="highlight-js notranslate"> <div class="highlight"> <pre>let thread = gThreadManager.currentThread; while (thread.hasPendingEvents()) thread.processNextEvent(true); </pre> </div> </div> </section> <section id="debugging-xpcshell-tests"> <h2>Debugging xpcshell-tests<a class="headerlink" href="https://firefox--source--docs-mozilla-org.translate.goog/testing/xpcshell/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#debugging-xpcshell-tests" title="Link to this heading"></a></h2> <section id="running-unit-tests-under-the-javascript-debugger"> <h3>Running unit tests under the javascript debugger<a class="headerlink" href="https://firefox--source--docs-mozilla-org.translate.goog/testing/xpcshell/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#running-unit-tests-under-the-javascript-debugger" title="Link to this heading"></a></h3> </section> <section id="via-jsdebugger"> <h3>Via –jsdebugger<a class="headerlink" href="https://firefox--source--docs-mozilla-org.translate.goog/testing/xpcshell/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#via-jsdebugger" title="Link to this heading"></a></h3> You can specify flags when issuing the <code class="docutils literal notranslate">xpcshell-test</code> command that will cause your test to stop right before running so you can attach the <a class="reference external" href="https://firefox--source--docs-mozilla-org.translate.goog/docs/Tools/Tools_Toolbox?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">javascript debugger</a>. Example: <div class="highlight-bash notranslate"> <div class="highlight"> <pre>$ ./mach xpcshell-test --jsdebugger browser/components/tests/unit/test_browserGlue_pingcentre.js 0:00.50 INFO Running tests sequentially. ... 0:00.68 INFO "" 0:00.68 INFO "*******************************************************************" 0:00.68 INFO "Waiting for the debugger to connect on port 6000" 0:00.68 INFO "" 0:00.68 INFO "To connect the debugger, open a Firefox instance, select 'Connect'" 0:00.68 INFO "from the Developer menu and specify the port as 6000" 0:00.68 INFO "*******************************************************************" 0:00.68 INFO "" 0:00.71 INFO "Still waiting for debugger to connect..." ... </pre> </div> </div> At this stage in a running Firefox instance: <ul class="simple"> <li>Go to the three-bar menu, then select <code class="docutils literal notranslate">More tools</code> -> <code class="docutils literal notranslate">Remote Debugging</code></li> <li>A new tab is opened. In the Network Location box, enter <code class="docutils literal notranslate">localhost:6000</code> and select <code class="docutils literal notranslate">Connect</code></li> <li>You should then get a link to ``Main Process``, click it and the Developer Tools debugger window will open.</li> <li>It will be paused at the start of the test, so you can add breakpoints, or start running as appropriate.</li> </ul> If you get a message such as: <div class="highlight-default notranslate"> <div class="highlight"> <pre> 0:00.62 ERROR Failed to initialize debugging: Error: resource://devtools appears to be inaccessible from the xpcshell environment. This can usually be resolved by adding: firefox-appdir = browser to the xpcshell.toml manifest. It is possible for this to alter test behevior by triggering additional browser code to run, so check test behavior after making this change. </pre> </div> </div> This is typically a test in core code. You can attempt to add that to the xpcshell.toml, however as it says, it might affect how the test runs and cause failures. Generally the firefox-appdir should only be left in xpcshell.toml for tests that are in the browser/ directory, or are Firefox-only. </section> </section> <section id="running-unit-tests-under-a-c-debugger"> <h2>Running unit tests under a C++ debugger<a class="headerlink" href="https://firefox--source--docs-mozilla-org.translate.goog/testing/xpcshell/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#running-unit-tests-under-a-c-debugger" title="Link to this heading"></a></h2> <section id="via-debugger-and-debugger-interactive"> <h3>Via <code class="docutils literal notranslate">--debugger and -debugger-interactive</code><a class="headerlink" href="https://firefox--source--docs-mozilla-org.translate.goog/testing/xpcshell/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#via-debugger-and-debugger-interactive" title="Link to this heading"></a></h3> You can specify flags when issuing the <code class="docutils literal notranslate">xpcshell-test</code> command that will launch xpcshell in the specified debugger (implemented in <a class="reference external" href="https://translate.google.com/website?sl=pl&tl=iw&hl=en-GB&u=https://bugzilla.mozilla.org/show_bug.cgi?id%3D382682">bug 382682</a>). Provide the full path to the debugger, or ensure that the named debugger is in your system PATH. Example: <div class="highlight-bash notranslate"> <div class="highlight"> <pre>$ ./mach xpcshell-test --debugger gdb --debugger-interactive netwerk/test/unit/test_resumable_channel.js # js>_execute_test(); ...failure or success messages are printed to the console... # js>quit(); </pre> </div> </div> On Windows with the VS debugger: <div class="highlight-bash notranslate"> <div class="highlight"> <pre>$ ./mach xpcshell-test --debugger devenv --debugger-interactive netwerk/test/test_resumable_channel.js </pre> </div> </div> Or with WinDBG: <div class="highlight-bash notranslate"> <div class="highlight"> <pre>$ ./mach xpcshell-test --debugger windbg --debugger-interactive netwerk/test/test_resumable_channel.js </pre> </div> </div> Or with modern WinDbg (WinDbg Preview as of April 2020): <div class="highlight-bash notranslate"> <div class="highlight"> <pre>$ ./mach xpcshell-test --debugger WinDbgX --debugger-interactive netwerk/test/test_resumable_channel.js </pre> </div> </div> </section> <section id="debugging-xpcshell-tests-in-a-child-process"> <h3>Debugging xpcshell tests in a child process<a class="headerlink" href="https://firefox--source--docs-mozilla-org.translate.goog/testing/xpcshell/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#debugging-xpcshell-tests-in-a-child-process" title="Link to this heading"></a></h3> To debug the child process, where code is often being run in a project, set MOZ_DEBUG_CHILD_PROCESS=1 in your environment (or on the command 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: <div class="highlight-bash notranslate"> <div class="highlight"> <pre>$ MOZ_DEBUG_CHILD_PROCESS=1 ./mach xpcshell-test test_simple_wrap.js CHILDCHILDCHILDCHILD debug me @13476 </pre> </div> </div> </section> <section id="debug-both-parent-and-child-processes"> <h3>Debug both parent and child processes<a class="headerlink" href="https://firefox--source--docs-mozilla-org.translate.goog/testing/xpcshell/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#debug-both-parent-and-child-processes" title="Link to this heading"></a></h3> Use MOZ_DEBUG_CHILD_PROCESS=1 to attach debuggers to each process. (For gdb at least, this means running separate copies of gdb, one for each process.) </section> </section> </section> </div> </div> <footer> <div class="rst-footer-buttons" role="navigation" aria-label="Footer"><a href="https://firefox--source--docs-mozilla-org.translate.goog/testing/mochitest-plain/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB" class="btn btn-neutral float-left" title="Mochitest" accesskey="p" rel="prev"> Previous</a> <a href="https://firefox--source--docs-mozilla-org.translate.goog/testing/tps/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB" class="btn btn-neutral float-right" title="TPS" accesskey="n" rel="next">Next </a> </div> <hr> <div role="contentinfo"> </div> Built with <a href="https://translate.google.com/website?sl=pl&tl=iw&hl=en-GB&u=https://www.sphinx-doc.org/">Sphinx</a> using a <a href="https://translate.google.com/website?sl=pl&tl=iw&hl=en-GB&u=https://github.com/readthedocs/sphinx_rtd_theme">theme</a> provided by <a href="https://translate.google.com/website?sl=pl&tl=iw&hl=en-GB&u=https://readthedocs.org">Read the Docs</a>. </footer> </div> </div> </section> </div> <script> jQuery(function () { SphinxRtdTheme.Navigation.enable(true); }); </script> <script>function gtElInit() {var lib = new google.translate.TranslateService();lib.translatePage('pl', 'iw', function () {});}</script> <script src="https://translate.google.com/translate_a/element.js?cb=gtElInit&hl=en-GB&client=wt" type="text/javascript"></script> </body> </html>