Reference Browser not supported unless --firefox-apk-component is set

[Rob--W]

Is this a feature request or a bug?

Bug

What is the current behavior?

Upon running the following:

web-ext run -t firefox-android --android-device=DEVICEID_HERE  --firefox-apk=org.mozilla.reference.browser

... the Reference Browser app (https://github.com/mozilla-mobile/reference-browser) is not launched and the following error is displayed:

Error: Activity class {org.mozilla.reference.browser/org.mozilla.reference.browser.App} does not exist.

What is the expected or desired behavior?

The reference browser should be launched. As a work-around, I have to add --firefox-apk-component=BrowserActivity .

To fix this, we would have to recognize the special component at

web-ext/src/util/adb.js

Lines 314 to 315 in 82c4250

	if (!apkComponent) {
	apkComponent = '.App';

Version information (for bug reports)

node --version && npm --version && web-ext --version

v14.13.0
6.14.7
5.2.0

[rpl]

mentor: @rpl

[krush11]

Hi, i would llike to work on this but i as this would be my first contribution i would need help. How do i pinpoint the file where i might need to make changes?

[rpl]

@krush11 Welcome!

Hi, i would llike to work on this but i as this would be my first contribution i would need help. How do i pinpoint the file where i might need to make changes?

@Rob--W did link that in the issue description.

Given that this would be your first contribution, I suggest you to also:

• take a look to the contribution guide here: https://github.com/mozilla/web-ext/blob/master/CONTRIBUTING.md
• try to run the existing tests before making any chance, to be sure that the development environment is worked correctly

Let us know if you get stuck or have some questions to ask

[krush11]

i have built and run tests. But i have no idea how to proceed. Can you suggest me anything which might help?

[rpl]

i have built and run tests. But i have no idea how to proceed. Can you suggest me anything which might help?

@krush11 Sure thing

Step 0: Be able to reproduce the issue

The first step to fix an issue is always "understanding it and be sure to know how to reproduce it".

In this case the issue is related to web-ext run used to run an extension on the "Reference Browser" android application.

And so I would start by trying to:

• install the "Reference Browser" on an android device or android emulator
• create a small test extension or use one of the simple examples in the mdn/webextensions-examples repository (e.g. borderify is a small one that you could use: https://github.com/mdn/webextensions-examples/tree/master/borderify)
• try to run the test extension on the "Reference Browser" application using the web-ext run command in the issue description

you can (and should) learn more about the web-ext run cli option available from the following two doc pages:

• https://extensionworkshop.com/documentation/develop/getting-started-with-web-ext
• https://extensionworkshop.com/documentation/develop/web-ext-command-reference/

Be sure to be able to reproduce the issue as described by Rob, and then the workaround described in the issue description (and start question yourself about why that works).

Step 1.1: Learn more about the domain (technical concepts, jargon etc) if needed

There may be concepts or jargon that you may not know yet, especially if you have never looked into how android applications work (e.g. what is an apk? what is an apk component?), you may gave a look to some android developer docs to try to find the meaning of those concepts on your own first.

Learning how to look for answers is an important skill to develop, as mentors it is important that we give you the chance to try to look for those as many answers as possible on your own, and providing all answers upfront would prevent you from trying and get better over the time.

If you are unable to find a good answer or one that does really convince you, you shouldn't feel guilty, it is pretty normal in the initial learning phases. Feel free to ask (hopefully specific enough) questions and we will be happy to provide you the details that you didn't figure out yet.

Step 1.2: "Read the source, Luke!"

(I couldn't resist, I had to quote "star wars" here :-))

Another important step is "finding out which part of the source code of the project is providing the feature related to the issue you are looking into", read it and try to understand as much of that source code as possible (and figure out what other source modules may be useful to read).

The following source files are some of the ones that will be useful to read and understand to fix this particular issue (with associated the "questions" that I would ask myself while looking for fixing this issue if I didn't knew the project source code already, and which are the related source code that should "answer those questions"):

• where is the source code that provide the communication channel between the developer machine and the android device or emulator? https://github.com/mozilla/web-ext/blob/master/src/util/adb.js
• where is the source code of the components that orchestrate the steps needed to run an android app, install the extension into it and then reload automatically when the source changes? https://github.com/mozilla/web-ext/blob/master/src/extension-runners/firefox-android.js
• where the web-ext run command is implemented? https://github.com/mozilla/web-ext/blob/master/src/cmd/run.js

Step 1.3: "Figure out the change needed to fix the issue"

At this point, based on what you learned in the previous steps, it is time to figure out what kind of changes are needed.

With the help of the reading done in step 1.2 you should identify where you may want to try to apply some change and have an understanding of why, and so it is to try to apply the changes and they try to reproduce the issue again and see if the change did provide the behavior you expected.

Adding some logging and try to reproduce the issue again could help you to figure out some details that you may be initially missing.

This is also the phase where you should not fear to make changes that may break more instead of fixing the issue:

never never never fear to break something in the source code while experimenting locally

experimenting is important even when it doesn't work, e.g. because it provides you a feedback on your level of understanding and it helps you to correct the picture that you are building in your mind about how the entire system works.

The more detailed and precise is the picture you got of the entire system, the easier will become for you to figure out what to do even before trying to apply any change. It does feel like magic initially but it is really not, it is just practice, that practice does train your brain to provide answers based on how your brain does picture the system you are working on.

Closing notes

Give a try to these pointers and suggestions, and then feel free to ping me again to ask some more specific questions on the issues that you may be facing by doing so.

Happy hacking!

[ankushduacodes]

@Rob--W @rpl I would like to take on this issue. Please let me know if I may.

[rpl]

@Rob--W @rpl I would like to take on this issue. Please let me know if I may.

Hi @ankushduacodes,
Given that @krush11 didn't open a pull request and didn't ask for help over the last couple of weeks, I think that we can now consider this issue open for another contributor that is looking for a good first bug to work on.

The comments #2041 (comment), #2041 (comment) and #2041 (comment) should provide you some pointers about how to get started.

Let us know if you have questions or you get stuck on some issue and you need help to figure it out.

[ankushduacodes]

Thank you @rpl, I will take a look at this issue and let you know if I need any help.
Could you please assign me to this issue?
Thank you!...

[rpl]

Thank you @rpl, I will take a look at this issue and let you know if I need any help.
Could you please assign me to this issue?
Thank you!...

@ankushduacodes we don't usually assign the issue until a contributor did create a pull request, but in the meantime we do "gate keep" the issue to give the last contributor that wanted to work on the good first bug some time to dig into the issue and create the PR (usually a couple of weeks), asking new contributors to look to one of the other good first bugs in the meantime.

[ankushduacodes]

@rpl I have correctly installed and ran the tests. the tests are running fine.
I tried to follow the steps outlined in this comment.
I have downloaded the extension and tried to run on normal firefox (ie. stable version of firefox). and it runs as expected as it adds 5px red border around any website ending with .mozilla.org.
I have also installed the reference browser on my device using the guide provided by reference browser repo.
when I try to run the web-ext run -t firefox-android it gives me adb error:
s: No adb executable has been found. You can Use --adb-bin, --adb-host/--adb-port to configure it manually if needed.

What is the step that I am doing wrong here?

(PS: I have connected my android device to my mac and USB debugging on my phone is ON)

[rpl]

@rpl I have correctly installed and ran the tests. the tests are running fine.
I tried to follow the steps outlined in this comment.
I have downloaded the extension and tried to run on normal firefox (ie. stable version of firefox). and it runs as expected as it adds 5px red border around any website ending with .mozilla.org.
I have also installed the reference browser on my device using the guide provided by reference browser repo.
when I try to run the web-ext run -t firefox-android it gives me adb error:
s: No adb executable has been found. You can Use --adb-bin, --adb-host/--adb-port to configure it manually if needed.

What is the step that I am doing wrong here?

@ankushduacodes You are just missing the adb tool executable. My apologies, I should have explicitly mention and link in my initial guidance comment this additional doc page (which provides more details about how to setup a developer machine for android, in particular to install adb):

https://extensionworkshop.com/documentation/develop/developing-extensions-for-firefox-for-android/#set-up-your-computer-and-android-emulator-or-device

adb means "Android Debug Bridge" and it is the tool that web-ext does use internally to interact with the android device or emulator (to learn more about what adb is you may also want to look to the following doc page: https://developer.android.com/studio/command-line/adb).

[ankushduacodes]

@rpl I was able to set up the adb and I actually was able to accidentally reproduce the issue on hand, as when I tried to run web-ext using following command web-ext run -s /Users/ankushdua/Documents/GitHub/web-ext/borderify -t firefox-android --android-device <DEVICE ID> --firefox-apk org.mozilla.reference.browser

I gave me the exact error that is mentioned in the issue description.
but when I ran web-ext run -s /Users/ankushdua/Documents/GitHub/web-ext/borderify -t firefox-android --android-device <DEVICE ID> --firefox-apk org.mozilla.reference.browser --firefox-apk-component=BrowserActivity
Every thing worked fine.

So now, my step would be to look for the how and why apk-component is used, Right?

[ankushduacodes]

@rpl So, Following is how I have thought of solving this issue.

web-ext/src/util/adb.js

Lines 323 to 329 in 82c4250

	if (apkComponent.startsWith('.')) {
	for (const browser of packageIdentifiers) {
	if (apk === browser || apk.startsWith(`${browser}.`)) {
	apkComponent = browser + apkComponent;
	}
	}
	}

above code snippet will look something like:

    if (apkComponent.startsWith('.')) {
      for (const browser of packageIdentifiers) {
        if (apk === browser || apk.startsWith(`${browser}.`)) {
          if (apk === 'org.mozilla.reference.browser' ||
            apk.startsWith('org.mozilla.reference.browser')) {
            if (apkComponent === '.App') {
              apkComponent = '.BrowserActivity';
            }
          }
          apkComponent = browser + apkComponent;
        }
      }
    }

I know this is a hackish way to solve the problem, Any thoughts or suggestions?

One more question: How do I get log.debug() statements to print on the console?

[rpl]

@rpl So, Following is how I have thought of solving this issue.

web-ext/src/util/adb.js

Lines 323 to 329 in 82c4250

	if (apkComponent.startsWith('.')) {
	for (const browser of packageIdentifiers) {
	if (apk === browser || apk.startsWith(`${browser}.`)) {
	apkComponent = browser + apkComponent;
	}
	}
	}

...
I know this is a hackish way to solve the problem, Any thoughts or suggestions?

I think that something like the following would do and be a bit less hacky:

if (!apkComponent) {
  if (apk === 'org.mozilla.reference.browser') {
    apkComponent = '.BrowserActivity';
  } else {
    apkComponent = '.App';
  }
}

Or even better, we could create an explicit map of default apkComponent values keyed by apk
(which may make it easier to manage the mapping over the time and make it a bit more explicit) e.g.:

// In src/firefox/package-identifiers.js something like:
export const defaultApkComponents = {
  'org.mozilla.reference.browser': '.BrowserActivity',
}; 

// then in src/utils/adb.js
import packageIdentifiers, {defaultApkComponents} from '../firefox/package-identifiers';

...

  if (!apkComponent) {
    if (defaultApkComponents[apk]) {
       apkComponent = defaultApkComponents[apk];
    } else {
      // Fallback to .App by default.
      apkComponent = '.App';
    }
  }

I think that I like this last approach. Let me know how that sounds to you.

One more question: How do I get log.debug() statements to print on the console?

The debug logs are printed on the console while web-ext is running in verbose mode, and so you should be able to see them printed in the console using the --verbose cli option.

[ankushduacodes]

@rpl I am very new to javascript world, while I knew this way of importing and export modules, it never crossed my mind. Looking at the codebase of web-ext, its very explicit in a sense that there are not many string literal comparisons. That's why I was feeling like my solution was going to work but wasn’t up to the standards.

Thank you for making me understand this!....😄