tips_for_test_migration.md

What is the original test about?

Read the existing test, run it and understand what it is asserting. The shared methods used in those tests should be in one of the following files

• devtools/client/aboutdebugging/test/head.js
• devtools/client/shared/test/shared-head.js

Is this already ported?

Sometimes we may already have implemented the test as a side-effect of another bug, so try to check if by any chance this has not already been ported to the new about:debugging.

Can it be ported?

Identify if the features used in the test to migrate are already implemented in the new about:debugging. If they are not, either:

• a bug already exists to implement the feature, block the migration bug on it, and if the blocking bug is P3 downgrade the priority to P3
• no bug exists, check with the team if the feature is worth porting, and wether it deserves a dedicated implementation bug

Assuming now the feature is ready we can start the test migration.

Create the new test file

Create a new browser mochitest in devtools/client/aboutdebugging-new/test/browser/. The name should be consistent with the existing files in aboutdebugging-new/test/browser/.

Of course if it makes sense to simply modify an existing test, this is also an option.

Add a comment to mention that this test comes from a test migration, for instance // This is a migration from: // https://searchfox.org/mozilla-central/source/devtools/client/aboutdebugging/test/browser_addons_debug_webextension.js.

Update browser.ini

If you created a new test, you should update browser.ini with the new entry. Check in the old about:debugging browser.ini if any specific tags or skip-ifs are applied to the original test. They probably need to be applied to the migrated test as well. Be carefulin the browser.ini file, the properties applied to a test are located after the test:

[test1.js]
tags=some-tag
skip-if=verify
[test2.js]
[test3.js]

In the example above, the tags & skip-if apply to test1.js, not to test2.js!

Write it as if it was a new test

If you start with a completely new file, you may copy paste the existing test in it and update it bit by bit to be compatible with the new about:debugging. However despite some similarities, most helpers and classnames used in the old about:debugging test suite don't have a direct equivalent in the new about:debugging. Therefore it might be better to consider this as writing a new test based on specifications infered from the existing test to migrate.

I personally copy paste the original test in order to already have the structure, the info() call, the comments, but then I replace the whole implementation.

Run the test as often as possible

It is tempting to just write the test code in one sitting and hoping for the best, but browser mochitests are quite fragile and sometimes very hard to debug. Start with the simplest skeleton that runs:

add_task(async function() {
  const { document, tab } = await openAboutDebugging();
  ok(true, "Just a dummy assert to please the test harness");
  await removeTab(tab);
});

and add to it bit by bit, regularly running the test to check everything is still fine.

Use shared helpers

Remember to check the existing tests in aboutdebugging-new/test/browser/ to find patterns you can reuse, and remember to check helper methods in head.js and in the helper_*.js files. Do not hesitate to refactor those files as you go. Their APIs have usually very few consumers, and they are completely contained to about:debugging.

Duplicate resources

If the existing test relies on additional resources (html, js, extensions) you may duplicate those files in devtools/client/aboutdebugging-new/test/browser/resources.

Final verification

Make sure the test passes, with --verify:

./mach test path/to/test.js --verify --headless

In normal and debug mode:

# in your mozconfig
ac_add_options --enable-debug

Keep the original test for now

Once you are done with the new test, do not delete the original test. Until the old about:debugging is removed, we don't want to lose any test coverage.