diff options
Diffstat (limited to 'devtools/client/aboutdebugging/documentation')
5 files changed, 469 insertions, 0 deletions
diff --git a/devtools/client/aboutdebugging/documentation/ANDROID_BUILD.md b/devtools/client/aboutdebugging/documentation/ANDROID_BUILD.md new file mode 100644 index 0000000000..42d1a52520 --- /dev/null +++ b/devtools/client/aboutdebugging/documentation/ANDROID_BUILD.md @@ -0,0 +1,60 @@ +# Build Firefox for Android + +## When do you need to build Firefox for Android + +If a remote debugging change impacts the server (file located in `devtools/server` or in `devtools/shared`), you will not be able to test it with a device which runs the release version of Firefox for Android. For the purpose of remote debugging, your local build of Firefox Desktop where you will test about:debugging runs the content of `devtools/client` (including `devtools/client/aboutdebugging`). And `devtools/server` runs on the device. So as soon as you are developing or testing a patch that needs to update the server and is about USB debugging, you need to build Firefox for Android and deploy it on a test device. + +## Setup your environment + +This will be a short documentation focused on the typical patches you may write for about:debugging. For a more complete documentation, you can refer to https://developer.mozilla.org/en-US/docs/Mozilla/Developer_guide/Build_Instructions/Simple_Firefox_for_Android_build. + +The whole setup needs to download several gigabytes of dependencies so try to have a fast internet connection to follow those steps. + +### Clone mozilla-central + +It is recommended to create a new clone of mozilla-central for your Firefox for Android builds. + +``` + hg clone https://hg.mozilla.org/mozilla-central mozilla-central-android + cd mozilla-central-android +``` + +### Run bootstrap + +Next simply run `mach bootstrap` and select the third option `3. Firefox for Android Artifact Mode` + +``` + > ./mach bootstrap + Please choose the version of Firefox you want to build: + 1. Firefox for Desktop Artifact Mode + 2. Firefox for Desktop + 3. Firefox for Android Artifact Mode + 4. Firefox for Android + > 3 +``` + +Follow the instructions, it will take some time as it needs to download a lot of dependencies. At the end it will provide you with a template you should use to create a `.mozconfig` file. You can use the proposed content without changing anything. + +### Enable USB debugging on your phone + +If you already used your device for USB debugging, this should already be enabled, but we will repeat the steps here. + +In the Settings menu, choose "About" and scroll down to the Build Number option. There's a hidden option there to activate "developer mode": tap the Build Number option seven times. You’ll see a countdown, and then a "Developer Options" menu will appear in your Settings. Don’t worry — you can turn this off whenever you like. The last step is to enable USB Debugging in the Developer Options menu. + +## Build and deploy to your phone + +Connect your phone to your computer with a USB cable. Then run: + +``` + ./mach build + ./mach package + ./mach install +``` + +At this step if you go to the list of applications on your phone, you should be able to spot a "Fennec" application. The fullname will be slightly different, for instance for me it is called "Fennec jdescottes". You can then run the application from your desktop command-line: + +``` + ./mach run +``` + +Sometimes this will fail with `WARNING: unable to launch Firefox for Android`. In that case you can simply start the application on your phone, as you would start any other application. diff --git a/devtools/client/aboutdebugging/documentation/GECKOVIEW_EXAMPLE_BUILD.md b/devtools/client/aboutdebugging/documentation/GECKOVIEW_EXAMPLE_BUILD.md new file mode 100644 index 0000000000..d34c9b2dfe --- /dev/null +++ b/devtools/client/aboutdebugging/documentation/GECKOVIEW_EXAMPLE_BUILD.md @@ -0,0 +1,66 @@ +# Build GeckoView Example + +## When do you need to build GeckoView Example + +If a remote debugging change impacts the server (file located in `devtools/server` or in `devtools/shared`), you will not be able to test it without building your GeckoView Example. For the purpose of remote debugging, your local build of Firefox Desktop where you will test about:debugging runs the content of `devtools/client` (including `devtools/client/aboutdebugging`). And `devtools/server` runs on the device. So as soon as you are developing or testing a patch that needs to update the server and is about USB debugging, you need to build GeckoView Example and deploy it on a test device. + +## Setup your environment + +This will be a short documentation focused on the typical patches you may write for about:debugging. For a more complete documentation, you can refer to https://mozilla.github.io/geckoview/ and https://developer.mozilla.org/en-US/docs/Mozilla/Developer_guide/Build_Instructions/Simple_Firefox_for_Android_build. + +The whole setup needs to download several gigabytes of dependencies so try to have a fast internet connection to follow those steps. + +### Clone mozilla-central + +It is recommended to create a new clone of mozilla-central for your GeckoView Example builds. + +``` + hg clone https://hg.mozilla.org/mozilla-central mozilla-central-gecko-view + cd mozilla-central-gecko-view +``` + +### Run bootstrap + +Next simply run `mach bootstrap` and select the third option `3. GeckoView/Firefox for Android Artifact Mode` + +``` + > ./mach bootstrap + Please choose the version of Firefox you want to build: + 1. Firefox for Desktop Artifact Mode + 2. Firefox for Desktop + 3. GeckoView/Firefox for Android Artifact Mode + 4. GeckoView/Firefox for Android + > 3 +``` + +Follow the instructions, it will take some time as it needs to download a lot of dependencies. At the end it will provide you with a template you should use to create a `.mozconfig` file. You can use the proposed content without changing anything. + +### Enable USB debugging on your phone + +If you already used your device for USB debugging, this should already be enabled, but we will repeat the steps here. + +In the Settings menu, choose "About" and scroll down to the Build Number option. There's a hidden option there to activate "developer mode": tap the Build Number option seven times. You’ll see a countdown, and then a "Developer Options" menu will appear in your Settings. Don’t worry — you can turn this off whenever you like. The last step is to enable USB Debugging in the Developer Options menu. + +## Build and deploy to your phone + +Connect your phone to your computer with a USB cable. Then run: + +``` + ./mach build + ./mach package + ./mach android install-geckoview_example +``` + +At this step if you go to the list of applications on your phone, you should be able to spot a "GeckoView Example" application. + +## Reflect changes + +If you change server files that impact GeckoView, you need to build and install again. Reflect the changes by: + +``` + ./mach build faster + ./mach package + ./mach android install-geckoview_example +``` + +Once you built all, the changes under `devtools/server` and `devtools/shared` can be built with `faster` option. This should be faster. diff --git a/devtools/client/aboutdebugging/documentation/GECKOVIEW_REFERENCE_BROWSER_BUILD.md b/devtools/client/aboutdebugging/documentation/GECKOVIEW_REFERENCE_BROWSER_BUILD.md new file mode 100644 index 0000000000..0036080a04 --- /dev/null +++ b/devtools/client/aboutdebugging/documentation/GECKOVIEW_REFERENCE_BROWSER_BUILD.md @@ -0,0 +1,152 @@ +# Build GeckoView Reference Browser + +## When do you need to build GeckoView Reference Browser + +If a remote debugging change impacts the server (file located in `devtools/server` or in `devtools/shared`), you will not be able to test it without building your GeckoView Reference Browser. For the purpose of remote debugging, your local build of Firefox Desktop where you will test about:debugging runs the content of `devtools/client` (including `devtools/client/aboutdebugging`). And `devtools/server` runs on the device. So as soon as you are developing or testing a patch that needs to update the server and is about USB debugging, you need to build GeckoView Reference Browser and deploy it on a test device. To build custom Reference Browser, need two modules of GeckoView and Reference Browser. + +## Setup your environment and build + +This will be a short documentation focused on the typical patches you may write for about:debugging. For a more complete documentation, you can refer to https://mozilla.github.io/geckoview/ and https://developer.mozilla.org/en-US/docs/Mozilla/Developer_guide/Build_Instructions/Simple_Firefox_for_Android_build. + +The whole setup needs to download several gigabytes of dependencies so try to have a fast internet connection to follow those steps. + +### Make empty directory + +It is recommended to create a new directory to build your GeckoView and Reference Browser. + +``` + mkdir geckoview-reference-browser + cd geckoview-reference-browser +``` + +### Build GeckoView + +#### Clone mozilla-central + +It is recommended to create a new clone of mozilla-central for your GeckoView builds. + +``` + hg clone https://hg.mozilla.org/mozilla-central mozilla-central-gecko-view + cd mozilla-central-gecko-view +``` + +#### Run bootstrap + +Next simply run `mach bootstrap` and select the third option `3. GeckoView/Firefox for Android Artifact Mode` + +``` + > ./mach bootstrap + Please choose the version of Firefox you want to build: + 1. Firefox for Desktop Artifact Mode + 2. Firefox for Desktop + 3. GeckoView/Firefox for Android Artifact Mode + 4. GeckoView/Firefox for Android + > 3 +``` + +Follow the instructions, it will take some time as it needs to download a lot of dependencies. At the end it will provide you with a template you should use to create a `.mozconfig` file. You can use the proposed content without changing anything. + +### Build + +Execute command below to build. + +``` + ./mach build + ./mach package + ./mach android archive-geckoview +``` + +If the build has finished successfully, the GeckoView AAR file will be created in your build output directory. You can find this file with following command: + +``` + > ls mozilla-central-gecko-view/<your-output-directory>/gradle/build/mobile/android/geckoview/outputs/aar + geckoview-withGeckoBinaries-debug.aar +``` + + +### Build Reference Browser + +#### Clone reference-browser + +It is recommended to create a new clone of reference-browser for your Reference Browser builds. + +``` + cd ../ + git clone https://github.com/mozilla-mobile/reference-browser + cd reference-browser +``` + +#### Create `local.properties` file + +`local.properties` file is necessary to specify the location of the Android SDK. Please write the absolute path of Android SDK with `sdk.dir` key. If you did `./mach bootstrap` once, Android SDK should already installed. You can find the directory whose name is like `android-sdk-<os-name>` under `~/.mozconfig/`. Thus, in mac osx case, the content of `local.properties` should be like below: + +``` +sdk.dir=/Users/xxxxxx/.mozbuild/android-sdk-osx +``` + +#### Edit `app/build.gradle` to build Reference Browser with above GeckoView + +You need to edit two places in `app/build.gradle`. + +1. Add `repositories` block with following content to bottom of file. <absolute path to AAR> is the directory which was created by `./mach android archive-geckoview` to build GeckoView. This should be like `/User/xxxxxx/mozilla-central-gecko-view/<your-output-directory>/gradle/build/mobile/android/geckoview/outputs/aar`. + +``` +repositories { + flatDir( + name: "localBuild", + dirs: "<absolute path to AAR>" + ) +} +``` + +2. Edit `geckoNightlyArmImplementation` + +``` +dependencies { + // ... + + //geckoNightlyArmImplementation Gecko.geckoview_nightly_arm + geckoNightlyArmImplementation( + name: 'geckoview-withGeckoBinaries-debug', + ext: 'aar' + ) + + // ... +} +``` + +#### Build and deploy to your phone + +Connect your phone to your computer with a USB cable. Then run: + +``` + ./gradlew build + ./gradlew installGeckoNightlyArmDebug +``` + +At this step if you go to the list of applications on your phone, you should be able to spot a "Reference Browser" application. + +### Enable USB debugging on your phone + +If you already used your device for USB debugging, this should already be enabled, but we will repeat the steps here. + +In the Settings menu, choose "About" and scroll down to the Build Number option. There's a hidden option there to activate "developer mode": tap the Build Number option seven times. You’ll see a countdown, and then a "Developer Options" menu will appear in your Settings. Don’t worry — you can turn this off whenever you like. The last step is to enable USB Debugging in the Developer Options menu on Reference Browser on your device. + +And, you can test with Reference Browser with custom GeckoView! + +## Reflect changes + +If you change codes in GeckoView, need to build and install again. Reflect the changes by: + +``` + cd mozilla-central-gecko-view + ./mach build faster + ./mach package + ./mach android archive-geckoview + cd ../ + cd reference-browser + ./gradlew build + ./gradlew installGeckoNightlyArmDebug +``` + +Once you built all, the changes under `devtools/server` and `devtools/shared` can build with `faster` option. This should be faster. diff --git a/devtools/client/aboutdebugging/documentation/TESTS.md b/devtools/client/aboutdebugging/documentation/TESTS.md new file mode 100644 index 0000000000..637e0cd18e --- /dev/null +++ b/devtools/client/aboutdebugging/documentation/TESTS.md @@ -0,0 +1,124 @@ +# Running Tests for the new about:debugging + +## Tests overview + +Tests are located in `devtools/client/aboutdebugging/test`. There are two subfolders, `browser` and `xpcshell`. `browser` contains our [browser mochitests](https://developer.mozilla.org/en-US/docs/Mozilla/Projects/Mochitest). Most of our tests are browser mochitests. `xpcshell` contains our [xpc-shell unit tests](https://developer.mozilla.org/en-US/docs/Mozilla/QA/Writing_xpcshell-based_unit_tests). At the moment of writing we only have one. + +## Test coverage + +You can get some code coverage information at https://codecov.io/gh/mozilla/gecko-dev/tree/master/devtools/client/aboutdebugging/src . The service is sometimes very slow, be patient! You might have to reload the page several times to get a result. + +## Running tests + +To run tests, you can use `./mach test {path}`. The path argument can be: +- relative/absolute path to a single test file: will run only this test +- relative/absolute path to a folder: will run all tests in the folder +- just a string: will match all the tests that contain this string + +A few examples below: + +``` +# Run browser_aboutdebugging_addons_manifest_url.js only + +./mach test devtools/client/aboutdebugging/test/browser/browser_aboutdebugging_addons_manifest_url.js + +# or + +./mach test browser_aboutdebugging_addons_manifest_url.js +``` + +``` +# Run all aboutdebugging tests + +./mach test devtools/client/aboutdebugging/test/browser/ + +# or (this works because all our tests start with "browser_aboutdebugging...") + +./mach test browser_aboutdebugging +``` + +Having consistent names for our tests can be very helpful to quickly run subset of tests: +``` +# Run all sidebar tests (will just run all the tests that start with browser_aboutdebugging_sidebar) + +./mach test browser_aboutdebugging_sidebar +``` + +## Troubleshooting + +### Fix the error "ADB process is already running" + +Some tests for about:debugging rely on starting and stopping the ADB (android debug bridge) process. However if the process is already running on your machine, the tests have no way to proceed and will fail with the message: + +``` +Error: The ADB process is already running on this machine, it should be stopped before running this test +``` + +In this case try to kill the process named `adb` in your process manager. If the adb process keeps coming back up, there must be an application that spawns the process. It might be a Firefox instance. Stop all your Firefox instances, then kill the `adb` process again and restart Firefox. (Note that in theory we should always stop adb correctly, but it seems there are still scenarios where this doesn't happen). + +### Pause a test + +If a test is not behaving as expected, it can be helpful to pause it at a certain step to have the time to investigate. You can add an await such as: + +``` +await new Promise(r => setTimeout(r, TIME)); // eg, replace TIME by 60000 to wait for 1 minute +``` + +Note that if you really need to wait for a long time, tests will timeout after some time and shutdown automatically. To avoid that, call `requestLongerTimeout(N);` somewhere in your test. `requestLongerTimeout()` takes an integer factor that is a multiplier for the the default 45 seconds timeout. So a factor of 2 means: Wait for at last 90s. + +### Attach a JS debugger to mochitests + +You can set debug tests with the DevTools debugger by passing the `--jsdebugger` argument to your tests. + +At the moment, you need to use `./mach mochitest` instead of `./mach test`, because of [Bug 1519369](https://bugzilla.mozilla.org/show_bug.cgi?id=1519369). This command is less flexible than `./mach test` so you will need to absolutely pass a relative path here. + +``` +./mach mochitest relative/path/to/test.js --jsdebugger +``` + +This will open a browser toolbox, with the debugger selected, before starting your test. Feel free to browse the files in the debugger and to add breakpoints. However your file is most likely not loaded yet, so the best is usually to add `debugger` statements in your code directly. + +This time the tests will wait for you to click on the "Browser chrome test" window to start. Do not be fooled by the "Run all tests" button on this window, clicking anywhere in the window will actually start the tests. + +## Other Tips + +### Headless mode + +Headless mode allows to run tests without opening a Firefox window and therefore blocking your computer. + +``` +./mach test browser_aboutdebugging --headless +``` + +### Memory leaks and Debug mode + +Running tests in debug mode is simply done by using a debug build (build with `ac_add_options --enable-debug`). The added value of debug mode is that it will also assert leaks. It can be very useful to run tests in debug mode if you modified things related to event listeners for instance, and you are not sure if you are cleanly removing all the listeners. + +### Test verify mode + +The test-verify mode - shortened as "TV" on our continuous integration platforms - will run a single test in a loop with some different flavors. The intent is to make it easier to catch intermittents. If you added or modified a test significantly, it is usually a good idea, to run it in test-verify mode at least once. + +``` +# Keeping the --headless argument, because the tests can be pretty slow +./mach test browser_aboutdebugging_addons_manifest_url.js --headless --test-verify +``` + +## Try server + +You can push your local changesets to our remote continuous integration server, try. This is useful if you made some significant changes and you would like to make sure nothing is broken in the whole DevTools tests suite, on any platform. + +There are many topics to cover here, but none are specific to about:debugging. Here are a few pointers: +- [Try overview](https://firefox-source-docs.mozilla.org/tools/try/index.html) +- [Selectors integrated with ./mach](https://firefox-source-docs.mozilla.org/tools/try/selectors/index.html) +- [Try syntax selector](https://firefox-source-docs.mozilla.org/tools/try/selectors/syntax.html) +- [Try fuzzy selector](https://firefox-source-docs.mozilla.org/tools/try/selectors/fuzzy.html) + +Below is an example of pushing to try using the try syntax selector. As the documentation says, this syntax is obscure and can be difficult to remember, but it is still widely used by developers in mozilla-central. + +``` +./mach try -b do -p linux64 -u xpcshell,mochitest-dt,mochitest-chrome --artifact +``` + +Refer to the [try syntax documentation](https://firefox-source-docs.mozilla.org/tools/try/selectors/syntax.html) to learn what the various parameters mean. + +Note that you need committer access level 1 in order to push to try. diff --git a/devtools/client/aboutdebugging/documentation/TESTS_REAL_DEVICES.md b/devtools/client/aboutdebugging/documentation/TESTS_REAL_DEVICES.md new file mode 100644 index 0000000000..f10709fb21 --- /dev/null +++ b/devtools/client/aboutdebugging/documentation/TESTS_REAL_DEVICES.md @@ -0,0 +1,67 @@ +# Running Tests with real USB connected devices for the new about:debugging + +This document explains how to test with real USB connected devices. + +## Tests overview + +The tests that use a real device are located in `devtools/client/aboutdebugging/test/browser/`and the name of tests starts with `browser_aboutdebugging_real`. These are normal mochitest, but we need to setup the environment before starting tests. + +## Setup environment +### Real device side +1. Enable USB debugging on your device +2. Launch Firefox +3. Enable USB debugging on your Firefox +4. Connect to your PC via USB + +You can refer to https://firefox-source-docs.mozilla.org/devtools-user/about_colon_debugging/index.html#connecting-to-a-remote-device + +### PC side +Setup the real device information to evaluate the validity in tests. + +1. Copy a sample file which is located at `devtools/client/aboutdebugging/test/browser/real/usb-runtimes-sample.json` and rename it for example to `devtools/client/aboutdebugging/test/browser/real/local-usb-runtimes.json`. +2. Edit the file. + + This is a JSON file like below, write your real device information in here. This example indicates that there should be one USB device and should be displayed `Pixel 2` as device name and `Firefox Nightly` as short name on the sidebar of about:debugging. Regarding the other information, please see `Detail of config file` section of this document. + +``` +[ + { + "sidebarInfo": { + "deviceName": "Pixel 2", + "shortName": "Firefox Nightly" + }, + ... + }, + ... +] +``` + +## Test +Normally, although we do test `./mach mochitest <path>`, to load the real device information created, specify the path as `USB_RUNTIME` environment variable, then do test. +For example, if the name of the saved file is `devtools/client/aboutdebugging/test/browser/real/local-usb-runtimes.json`, run all real device test with a command like the one below: + +``` +USB_RUNTIMES=devtools/client/aboutdebugging/test/browser/real/local-usb-runtimes.json ./mach mochitest devtools/client/aboutdebugging/test/browser/browser_aboutdebugging_real +``` + +If there is no `USB_RUNTIMES` environment variable, the tests will not run. This is also to avoid to run on try-server and so on. + +## Detail of config file + +``` +[ + { + "sidebarInfo": { + "deviceName": "Pixel 2", // This should display as device name on the sidebar. + "shortName": "Firefox Nightly" // This should display as short name on the sidebar. + }, + "runtimeDetails": { + "info": { + "name": "Mozilla Nightly", // This should display on the runtime info of runtime page. + "version": "64.0a1" // This should display on the runtime info of runtime page. + } + } + } + // Of course, you can append additional USB devices. Some tests can do with multiple devices. +] +``` |