47
edits
WebExtensions/Contribution Onramp: Difference between revisions
WebExtensions/Contribution Onramp (view source)
Revision as of 14:21, 6 November 2024
, 6 November 2024Update links, update locations (android -> shared, ini -> toml, jsm -> sys.mjs), add linting advice, add testing advice
(Document linting) |
(Update links, update locations (android -> shared, ini -> toml, jsm -> sys.mjs), add linting advice, add testing advice) |
||
| Line 20: | Line 20: | ||
In short: | In short: | ||
* Now, you need to set up your development environment by [https://firefox-source-docs.mozilla.org/contributing/contribution_quickref.html# | * Now, you need to set up your development environment by [https://firefox-source-docs.mozilla.org/contributing/contribution_quickref.html#bootstrap-a-copy-of-the-firefox-source-code cloning the source] with mercurial or [https://github.com/glandium/git-cinnabar/wiki/Mozilla:-A-git-workflow-for-Gecko-development with Git]. | ||
* Then you need to install dependencies with <code>mach bootstrap</code> for building Firefox. There are two ways to do this: | * Then you need to install dependencies with <code>mach bootstrap</code> for building Firefox. There are two ways to do this: | ||
** [recommended] Build Firefox using [https://firefox-source-docs.mozilla.org/contributing/build/artifact_builds.html Firefox Artifact builds]. If the issue only requires changes to privileged JavaScript code, we recommend you use this method. Artifact builds saves time because it downloads a pre-built version of Firefox sources and applies your local changes on it, instead of rebuilding all of the C++ and Rust pieces from scratch. | ** [recommended] Build Firefox using [https://firefox-source-docs.mozilla.org/contributing/build/artifact_builds.html Firefox Artifact builds]. If the issue only requires changes to privileged JavaScript code, we recommend you use this method. Artifact builds saves time because it downloads a pre-built version of Firefox sources and applies your local changes on it, instead of rebuilding all of the C++ and Rust pieces from scratch. | ||
| Line 37: | Line 37: | ||
== Testing == | == Testing == | ||
In order to land code in Firefox, you will need to create tests for your patches. For an overview of the different test systems Firefox uses, please see this [https:// | In order to land code in Firefox, you will need to create tests for your patches. For an overview of the different test systems Firefox uses, please see this [https://firefox-source-docs.mozilla.org/testing/automated-testing/index.html overview of automated testing]. In the WebExtension API code, most tests are either [https://firefox-source-docs.mozilla.org/testing/xpcshell/index.html xpcshell tests] or [https://firefox-source-docs.mozilla.org/testing/mochitest-plain/index.html (browser-chrome) mochitests]. Xpcshell tests are preferred because of the lower overhead. Browser tests need to be written when a test interfaces with browser UI, such as tabs or context menus. Browser tests are not supported on mobile; use mochitests if you need to run tests with a real browser on desktop and mobile. | ||
The easiest way to get started with tests is to look at existing tests: | The easiest way to get started with tests is to look at existing tests: | ||
| Line 43: | Line 43: | ||
** toolkit/components/extensions/test/xpcshell/ ([https://searchfox.org/mozilla-central/source/toolkit/components/extensions/test/xpcshell Searchfox link]) | ** toolkit/components/extensions/test/xpcshell/ ([https://searchfox.org/mozilla-central/source/toolkit/components/extensions/test/xpcshell Searchfox link]) | ||
** browser/components/extensions/test/xpcshell/ ([https://searchfox.org/mozilla-central/source/browser/components/extensions/test/xpcshell Searchfox link]) | ** browser/components/extensions/test/xpcshell/ ([https://searchfox.org/mozilla-central/source/browser/components/extensions/test/xpcshell Searchfox link]) | ||
** mobile/ | ** mobile/shared/components/extensions/test/xpcshell ([https://searchfox.org/mozilla-central/source/mobile/shared/components/extensions/test/xpcshell Searchfox link]) | ||
* Browser-chrome tests: | * Browser-chrome tests: | ||
** toolkit/components/extensions/test/browser/ ([https://searchfox.org/mozilla-central/source/toolkit/components/extensions/test/browser Searchfox link]) | ** toolkit/components/extensions/test/browser/ ([https://searchfox.org/mozilla-central/source/toolkit/components/extensions/test/browser Searchfox link]) | ||
** browser/components/extensions/test/browser/ ([https://searchfox.org/mozilla-central/source/browser/components/extensions/test/browser Searchfox link]) | ** browser/components/extensions/test/browser/ ([https://searchfox.org/mozilla-central/source/browser/components/extensions/test/browser Searchfox link]) | ||
* Mochitests: | |||
** toolkit/components/extensions/test/mochitest/ ([https://searchfox.org/mozilla-central/source/toolkit/components/extensions/test/mochitest Searchfox link]) | |||
* Firefox for Android mochitests: | * Firefox for Android mochitests: | ||
** mobile/ | ** mobile/shared/components/extensions/test/mochitest ([https://searchfox.org/mozilla-central/source/mobile/shared/components/extensions/test/mochitest Searchfox link]) | ||
=== Running tests === | === Running tests === | ||
| Line 60: | Line 63: | ||
=== Adding new tests === | === Adding new tests === | ||
Add your test to an existing file when it is small and fits in that test. Otherwise, create a new test file, and register the test file in one of the . | Add your test to an existing file when it is small and fits in that test. Otherwise, create a new test file, and register the test file in one of the .toml files in the same directory as your test, usually browser.toml or xpcshell-common.toml. | ||
After creating a new test file, run <code>mach build</code> before running tests. It is not necessary to rebuild if you are changing an existing test file. | After creating a new test file, run <code>mach build</code> before running tests. It is not necessary to rebuild if you are changing an existing test file. | ||
| Line 81: | Line 84: | ||
ExtensionTestUtils.loadExtension allows you to quickly generate a test extension, and its input parameters are documented at: | ExtensionTestUtils.loadExtension allows you to quickly generate a test extension, and its input parameters are documented at: | ||
https://searchfox.org/mozilla-central/rev/ | https://searchfox.org/mozilla-central/rev/aecb006bbb135d707ca4b8cea7572dd8abab6817/toolkit/components/extensions/ExtensionTestCommon.sys.mjs#483-507 | ||
Another common action in tests is to load a web page or extension page. | Another common action in tests is to load a web page or extension page. | ||
In xpcshell-tests, use ExtensionTestUtils.loadContentPage. | In xpcshell-tests, use ExtensionTestUtils.loadContentPage. | ||
In browser-chrome tests, the BrowserTestUtils namespace provides many useful test helpers, such as BrowserTestUtils.openNewForegroundTab to open a new tab. BrowserTestUtils is implemented and documented at https://searchfox.org/mozilla-central/source/testing/mochitest/BrowserTestUtils/BrowserTestUtils. | In browser-chrome tests, the BrowserTestUtils namespace provides many useful test helpers, such as BrowserTestUtils.openNewForegroundTab to open a new tab. BrowserTestUtils is implemented and documented at https://searchfox.org/mozilla-central/source/testing/mochitest/BrowserTestUtils/BrowserTestUtils.sys.mjs | ||
Running the tests (xpcshell tests and Firefox for Android mochitests) on the Android emulator requires some [https://wiki.mozilla.org/Mobile/Fennec/Android/Testing#Running_tests_on_the_Android_emulator additional setup of the local development environment]. | Running the tests (xpcshell tests and Firefox for Android mochitests) on the Android emulator requires some [https://wiki.mozilla.org/Mobile/Fennec/Android/Testing#Running_tests_on_the_Android_emulator additional setup of the local development environment]. | ||
| Line 92: | Line 95: | ||
=== Linting === | === Linting === | ||
Firefox source code have a consistent formatting and code style, which is enforced through [https://firefox-source-docs.mozilla.org/code-quality/lint/index.html linting]. Most extension code is written with JavaScript, which is linted via eslint. It is recommended to set up and run the linter locally (see [https://firefox-source-docs.mozilla.org/code-quality/lint/linters/eslint.html eslint docs]). When a patch has been submitted to Phabricator, [https://firefox-source-docs.mozilla.org/code-quality/static-analysis/index.html static analysis] will run and report style errors upon completion (which may take a while to run). The Try Server also offers linting (ES for eslint, per [https://wiki.mozilla.org/WebExtensions/Try_Server WebExtensions/Try Server]). | Firefox source code have a consistent formatting and code style, which is enforced through [https://firefox-source-docs.mozilla.org/code-quality/lint/index.html linting]. Most extension code is written with JavaScript, which is linted via eslint. It is recommended to set up and run the linter locally (see [https://firefox-source-docs.mozilla.org/code-quality/lint/linters/eslint.html eslint docs]). When a patch has been submitted to Phabricator, [https://firefox-source-docs.mozilla.org/code-quality/static-analysis/index.html static analysis] will run and report style errors upon completion (which may take a while to run). The Try Server also offers linting (ES for eslint, per [https://wiki.mozilla.org/WebExtensions/Try_Server WebExtensions/Try Server]). | ||
You can run linters on individual files as follows: | |||
<code>./mach lint [path(s) to file(s) and/or directories]</code> | |||
You can also run the linter on all local changes: | |||
<code>./mach lint --outgoing</code> | |||
== Submitting a Patch == | == Submitting a Patch == | ||