Fix refs and docs involving testBinaryPath (#4311)

detox/src/devices/common/drivers/android/tools/ApkValidator.js

@@ -1,6 +1,6 @@
 const DetoxRuntimeError = require('../../../../../errors/DetoxRuntimeError');
 
-const setupGuideHint = 'For further assistance, visit the Android setup guide: https://github.com/wix/Detox/blob/master/docs/Introduction.Android.md';
+const setupGuideHint = 'For further assistance, visit the project setup guide (select the Android tabs): https://wix.github.io/Detox/docs/introduction/project-setup';
 
 class ApkValidator {
   constructor(aapt) {

detox/src/devices/common/drivers/android/tools/ApkValidator.test.js

@@ -1,3 +1,4 @@
+
 describe('APK validation', () => {
 
   const binaryPath = 'mock-bin-path';

detox/src/devices/common/drivers/android/tools/__snapshots__/ApkValidator.test.js.snap

@@ -4,28 +4,28 @@ exports[`APK validation App APK validation should throw a descriptive error if a
 "App APK at path mock-bin-path was detected as the *test* APK!
 
 HINT: Your binary path was probably wrongly set in the active Detox configuration.
-For further assistance, visit the Android setup guide: https://github.com/wix/Detox/blob/master/docs/Introduction.Android.md"
+For further assistance, visit the project setup guide (select the Android tabs): https://wix.github.io/Detox/docs/introduction/project-setup"
 `;
 
 exports[`APK validation App APK validation should throw a specific error if AAPT throws 1`] = `
 "Failed to get details about the APK at path mock-bin-path. Root cause:
 Error: mock error
 
 HINT: Check that the binary path in the active Detox configuration has been set to a path of an APK file.
-For further assistance, visit the Android setup guide: https://github.com/wix/Detox/blob/master/docs/Introduction.Android.md"
+For further assistance, visit the project setup guide (select the Android tabs): https://wix.github.io/Detox/docs/introduction/project-setup"
 `;
 
 exports[`APK validation Test APK validation should throw a descriptive error if APK happens to be an app APK 1`] = `
 "Test APK at path mock-test-bin-path was detected as the *app* APK!
 
 HINT: Your test test-binary path was probably wrongly set in the active Detox configuration.
-For further assistance, visit the Android setup guide: https://github.com/wix/Detox/blob/master/docs/Introduction.Android.md"
+For further assistance, visit the project setup guide (select the Android tabs): https://wix.github.io/Detox/docs/introduction/project-setup"
 `;
 
 exports[`APK validation Test APK validation should throw a specific error if AAPT throws 1`] = `
 "Failed to get details about the APK at path mock-test-bin-path. Root cause:
 Error: mock error
 
 HINT: Check that the test-binary path in the active Detox configuration has been set to a path of an APK file.
-For further assistance, visit the Android setup guide: https://github.com/wix/Detox/blob/master/docs/Introduction.Android.md"
+For further assistance, visit the project setup guide (select the Android tabs): https://wix.github.io/Detox/docs/introduction/project-setup"
 `;

detox/src/devices/runtime/drivers/android/AndroidDriver.js

@@ -280,7 +280,7 @@ class AndroidDriver extends DeviceDriverBase {
       throw new DetoxRuntimeError({
         message: `The test APK could not be found at path: '${testApkPath}'`,
         hint: 'Try running the detox build command, and make sure it was configured to execute a build command (e.g. \'./gradlew assembleAndroidTest\')' +
-          '\nFor further assistance, visit the Android setup guide: https://github.com/wix/Detox/blob/master/docs/Introduction.Android.md',
+          '\nFor further assistance, visit the project setup guide (select the Android tabs): https://wix.github.io/Detox/docs/introduction/project-setup',
       });
     }
     return testApkPath;

detox/src/devices/runtime/drivers/android/__snapshots__/AndroidDriver.test.js.snap

@@ -4,5 +4,5 @@ exports[`Android driver App installation should throw if auto test-binary path r
 "The test APK could not be found at path: 'testApkPathOf(absolutePathOf(mock-bin-path))'
 
 HINT: Try running the detox build command, and make sure it was configured to execute a build command (e.g. './gradlew assembleAndroidTest')
-For further assistance, visit the Android setup guide: https://github.com/wix/Detox/blob/master/docs/Introduction.Android.md"
+For further assistance, visit the project setup guide (select the Android tabs): https://wix.github.io/Detox/docs/introduction/project-setup"
 `;

docs/introduction/partials/_project-setup-apps-android.mdx

@@ -2,23 +2,63 @@
 
 import FlavorizedCodeBlock from '@site/src/components/FlavorizedCodeBlock';
 
-Check **binaryPath** and **build** configs for `android.debug` and `android.release` mode in your Detox config:
+Check the **build** and **binaryPath** attributes for the `android.debug` and `android.release` Detox configs:
 
 ```js title=".detoxrc.js"
 module.exports = {
   apps: {
     'android.debug': {
       type: 'android.apk',
       // highlight-start
-      binaryPath: 'android/app/build/outputs/apk/debug/app-debug.apk',
-      build: 'cd android && ./gradlew assembleDebug assembleAndroidTest -DtestBuildType=debug'
+      build: 'cd android && ./gradlew assembleDebug assembleAndroidTest -DtestBuildType=debug',
+      binaryPath: 'android/app/build/outputs/apk/debug/app-debug.apk'
       // highlight-end
     },
     'android.release': {
       type: 'android.apk',
       // highlight-start
+      build: 'cd android && ./gradlew assembleRelease assembleAndroidTest -DtestBuildType=release',
+      binaryPath: 'android/app/build/outputs/apk/release/app-release.apk'
+      // highlight-end
+    },
+    // ...
+  },
+  // ...
+};
+```
+
+If you have a typical React Native project, these values should already be sufficient and correct.
+
+#### testBinaryPath
+
+In Android automation testing, there are in fact 2 app binaries involved:
+1. The _app_ APK, containing your app's code.
+2. The _test_ APK, containing _test_ code. That includes Detox's native code, Espresso and more.
+
+In some projects, it might make sense for the test APK to be generated over a separate flow, through which is may end up
+being put it some custom,
+[non-default path](https://stackoverflow.com/questions/43670463/where-is-the-test-apk-located-in-android-project).
+One such example is an optimization where the test APK is prebuilt once and used across multiple app variations. This is
+a place where the `testBinaryPath` attribute can come to the rescue; It can be applied in order to set the custom path
+to the test APK explicitly:
+
+```js title=".detoxrc.js"
+module.exports = {
+  apps: {
+    'android.debug': {
+      type: 'android.apk',
+      build: 'cd android && ./gradlew assembleDebug assembleAndroidTest -DtestBuildType=debug',
+      binaryPath: 'android/app/build/outputs/apk/debug/app-debug.apk',
+      // highlight-start
+      testBinaryPath: 'custom/path/to/app-debug-androidTest.apk'
+      // highlight-end
+    },
+    'android.release': {
+      type: 'android.apk',
       binaryPath: 'android/app/build/outputs/apk/release/app-release.apk',
-      build: 'cd android && ./gradlew assembleRelease assembleAndroidTest -DtestBuildType=release'
+      build: 'cd android && ./gradlew assembleRelease assembleAndroidTest -DtestBuildType=release',
+      // highlight-start
+      testBinaryPath: 'custom/path/to/app-release-androidTest.apk'
       // highlight-end
     },
     // ...
@@ -27,23 +67,26 @@ module.exports = {
 };
 ```
 
-If you have a typical React Native project, these values should already be correct.
+> Mind that in the common case, the `testBinaryPath` attributes is not explicitly required, simply because Detox knows
+how to locate it in one of the default paths automatically.
+
+#### Product flavors
 
-On the other hand, if your app has extra [`productFlavors`](https://developer.android.com/studio/build/build-variants#product-flavors)
-(let's imagine you have `driver` and `passenger` flavors of a taxi application), then you should rewrite your apps config
-for both **debug** and **release** configurations, e.g.:
+On even more advanced use cases, apps may have additional, custom [`productFlavors`](https://developer.android.com/studio/build/build-variants#product-flavors)
+(consider the case of a `driver` and `passenger` flavors of a taxi application). In this case, you should rewrite your apps config,
+for both **debug** and **release** configurations, according to those flavors, e.g.:
 
 <FlavorizedCodeBlock
   language="diff"
   header={'   apps: {\n'}
   flavors={['Driver', 'Passenger']}
 >
-  {(conf) => `\
-     '${conf.toLowerCase()}.android.debug': {
+  {(flavor) => `\
+     '${flavor.toLowerCase()}.android.debug': {
        type: 'android.apk',
 -      binaryPath: 'android/app/build/outputs/apk/debug/app-debug.apk',
-+      binaryPath: 'android/app/build/outputs/apk/${conf.toLowerCase()}/debug/app-${conf.toLowerCase()}-debug.apk',
++      binaryPath: 'android/app/build/outputs/apk/${flavor.toLowerCase()}/debug/app-${flavor.toLowerCase()}-debug.apk',
 -      build: 'cd android && ./gradlew assembleDebug assembleAndroidTest -DtestBuildType=debug',
-+      build: 'cd android && ./gradlew assemble${conf}Debug assemble${conf}DebugAndroidTest -DtestBuildType=debug',
++      build: 'cd android && ./gradlew assemble${flavor}Debug assemble${flavor}DebugAndroidTest -DtestBuildType=debug',
      },`}
 </FlavorizedCodeBlock>