detox 20.4.0 → 20.6.0

package/Detox-android/com/wix/detox/20.6.0/detox-20.6.0-javadoc.jar.md5

@@ -0,0 +1 @@
+c051f79d02bcc98757dd1ea06512a63b

package/Detox-android/com/wix/detox/20.6.0/detox-20.6.0-javadoc.jar.sha1

@@ -0,0 +1 @@
+bb48d0747cb607e73a01d64f5eb758ce00e376cb

package/Detox-android/com/wix/detox/20.6.0/detox-20.6.0-javadoc.jar.sha256

@@ -0,0 +1 @@
+b31397b81cdca47b2d5dc1aca7821f2691d236114064949ad8553fd81340fe02

package/Detox-android/com/wix/detox/20.6.0/detox-20.6.0-javadoc.jar.sha512

@@ -0,0 +1 @@
+6cec7c20f0d9643b98e2fa2f4740c9bb7a4b82ae3851069bb183e16ffcace8b0ceb07cf8d19316a960beb2330ea3e0a508df80cda1561242149ce3b16357d954

package/Detox-android/com/wix/detox/20.6.0/detox-20.6.0-sources.jar.md5

@@ -0,0 +1 @@
+6202d8d0f83dda9ed0c9d6962259350e

package/Detox-android/com/wix/detox/20.6.0/detox-20.6.0-sources.jar.sha1

@@ -0,0 +1 @@
+505b10faaca41e1b5e7f27b8829cd14aff6b5626

package/Detox-android/com/wix/detox/20.6.0/detox-20.6.0-sources.jar.sha256

@@ -0,0 +1 @@
+f4b81a4c2c1665975ac5be02698e288a311e3cd3c728ba9b05e72a1932f7482e

package/Detox-android/com/wix/detox/20.6.0/detox-20.6.0-sources.jar.sha512

@@ -0,0 +1 @@
+e355acd2730e5ca57bb7f2c092942b6dd98997645b43350fd2c80051f3f8a6840f2746cd2e8fbeae862ab4cac0fc6339b7f298e697f3bfb4124598370c4b2a54

package/Detox-android/com/wix/detox/20.6.0/detox-20.6.0.aar.md5

@@ -0,0 +1 @@
+f62ab63d03ba71b4776965696f3d4a88

package/Detox-android/com/wix/detox/20.6.0/detox-20.6.0.aar.sha1

@@ -0,0 +1 @@
+1a38f931edf9925af1d131a0e0a0822bd880dcc8

package/Detox-android/com/wix/detox/20.6.0/detox-20.6.0.aar.sha256

@@ -0,0 +1 @@
+4145b5a8078b613e10205937ffb3da254d006fe78fbb169d8b2cedb3d02c021c

package/Detox-android/com/wix/detox/20.6.0/detox-20.6.0.aar.sha512

@@ -0,0 +1 @@
+ab25979faccc1aa8200a637ea866a5fc59e35bf340170673a01253ae8ce479fb5b7af87167dbde2d43d5b536f3fb350b34b478bbf75f5e87d5276940283a8ab6

package/Detox-android/com/wix/detox/{20.4.0/detox-20.4.0.pom → 20.6.0/detox-20.6.0.pom}

@@ -3,7 +3,7 @@
   <modelVersion>4.0.0</modelVersion>
   <groupId>com.wix</groupId>
   <artifactId>detox</artifactId>
-  <version>20.4.0</version>
+  <version>20.6.0</version>
   <packaging>aar</packaging>
   <name>Detox</name>
   <description>Gray box end-to-end testing and automation library for mobile apps</description>

package/Detox-android/com/wix/detox/20.6.0/detox-20.6.0.pom.md5

@@ -0,0 +1 @@
+120956f03efbba5c9cec898b7da52efe

package/Detox-android/com/wix/detox/20.6.0/detox-20.6.0.pom.sha1

@@ -0,0 +1 @@
+b6c2c0740f1de17d7dc5671d096debbe7eb46dd3

package/Detox-android/com/wix/detox/20.6.0/detox-20.6.0.pom.sha256

@@ -0,0 +1 @@
+8fdf9933acc2bcc22588bc3cffb6348ab73f8100c5212f7e607e315bce59a265

package/Detox-android/com/wix/detox/20.6.0/detox-20.6.0.pom.sha512

@@ -0,0 +1 @@
+f3ae74b6397013d7a5af6ed08cbbd739f5e207df9463a6b6cb496bd1b9a87022f193b87207d6424f2b8b85e022836211215cd01eaa88f9adcea6515594f59e76

package/Detox-android/com/wix/detox/maven-metadata.xml

@@ -3,11 +3,11 @@
   <groupId>com.wix</groupId>
   <artifactId>detox</artifactId>
   <versioning>
-    <latest>20.4.0</latest>
-    <release>20.4.0</release>
+    <latest>20.6.0</latest>
+    <release>20.6.0</release>
     <versions>
-      <version>20.4.0</version>
+      <version>20.6.0</version>
     </versions>
-    <lastUpdated>20230228144344</lastUpdated>
+    <lastUpdated>20230322171518</lastUpdated>
   </versioning>
 </metadata>

package/Detox-android/com/wix/detox/maven-metadata.xml.md5

@@ -1 +1 @@
-cdc80e0982319a663e6f0e4ac720d785
+f72e8f5e279054eb2e8e8faab020aaab

package/Detox-android/com/wix/detox/maven-metadata.xml.sha1

@@ -1 +1 @@
-5cd147e3e28a8e1ae4b256edfabaac149e2c1387
+4e3513e973cd69a3ce1b30d0756ba26660ae1ba6

package/Detox-android/com/wix/detox/maven-metadata.xml.sha256

@@ -1 +1 @@
-0fd84cc6744732697aa0a9769b6febb6b432d765b4223b48c34a6b3bfd240483
+319540a82e8d028d9fe417155b17c95ae4d62f0cf9f18a751a1827a27acf1802

package/Detox-android/com/wix/detox/maven-metadata.xml.sha512

@@ -1 +1 @@
-452aea17d2dbacd7d844c8f9d370c9931ae1196ac85020666f60ed7d8ddfc561d783abcec6f3c3b6b3a677be57cdf0a8966fc8254876e079e4c2d5dd0a229288
+92f9a95efb7117c43c5df7765e56d81d8ef34b2413ef04e6133d7a3d51ccb88bec0aa80bba83d302ebe4dee638270ec57e03b0a3fc972e8552fd94365065fd3a

package/android/detox/src/full/java/com/wix/detox/common/UIExtensions.kt

@@ -0,0 +1,28 @@
+package com.wix.detox.common
+
+import android.view.View
+import android.view.ViewGroup
+
+fun View.forEachChild(callback: (child: View) -> Unit) {
+    if (this is ViewGroup) {
+        for (index in 0 until childCount) {
+            val child = getChildAt(index)
+            callback(child)
+        }
+    }
+}
+
+/**
+ * In-order traverse the view-hierarchy specified by a view, considered to be the hierarchy's root.
+ *
+ * @param view The hierarchy's root-view.
+ * @param callback A function to call per each view. Returning `false` from the callback indicates
+ *  a request to refrain from traversing the sub-hierarchy associated with the current view.
+ */
+fun traverseViewHierarchy(view: View, callback: (view: View) -> Boolean) {
+    if (callback(view)) {
+        view.forEachChild { child ->
+            traverseViewHierarchy(child, callback)
+        }
+    }
+}

package/android/detox/src/full/java/com/wix/detox/espresso/DetoxMatcher.java

@@ -12,15 +12,17 @@ import static androidx.test.espresso.matcher.ViewMatchers.isChecked;
 import static androidx.test.espresso.matcher.ViewMatchers.isDescendantOfA;
 import static androidx.test.espresso.matcher.ViewMatchers.isDisplayed;
 import static androidx.test.espresso.matcher.ViewMatchers.isDisplayingAtLeast;
+import static androidx.test.espresso.matcher.ViewMatchers.isFocused;
 import static androidx.test.espresso.matcher.ViewMatchers.isNotChecked;
 import static androidx.test.espresso.matcher.ViewMatchers.withContentDescription;
 import static androidx.test.espresso.matcher.ViewMatchers.withEffectiveVisibility;
 import static androidx.test.espresso.matcher.ViewMatchers.withTagValue;
 import static androidx.test.espresso.matcher.ViewMatchers.withText;
-import static androidx.test.espresso.matcher.ViewMatchers.isFocused;
 import static com.wix.detox.espresso.matcher.ViewMatchers.isMatchingAtIndex;
 import static com.wix.detox.espresso.matcher.ViewMatchers.isOfClassName;
 import static com.wix.detox.espresso.matcher.ViewMatchers.toHaveSliderPosition;
+import static com.wix.detox.espresso.matcher.ViewMatchers.withAccessibilityLabel;
+import static com.wix.detox.espresso.matcher.ViewMatchers.withShallowAccessibilityLabel;
 import static org.hamcrest.Matchers.allOf;
 import static org.hamcrest.Matchers.anyOf;
 import static org.hamcrest.Matchers.is;
@@ -43,6 +45,14 @@ public class DetoxMatcher {
         return allOf(withText(text), withEffectiveVisibility(Visibility.VISIBLE));
     }
 
+    public static Matcher<View> matcherForAccessibilityLabel(String label) {
+        return allOf(withAccessibilityLabel(label), withEffectiveVisibility(Visibility.VISIBLE));
+    }
+
+    public static Matcher<View> matcherForShallowAccessibilityLabel(String label) {
+        return allOf(withShallowAccessibilityLabel(label), withEffectiveVisibility(Visibility.VISIBLE));
+    }
+
     public static Matcher<View> matcherForContentDescription(String contentDescription) {
         return allOf(withContentDescription(contentDescription), withEffectiveVisibility(Visibility.VISIBLE));
     }

package/android/detox/src/full/java/com/wix/detox/espresso/action/GetAttributesAction.kt

@@ -10,6 +10,7 @@ import androidx.test.espresso.UiController
 import com.google.android.material.slider.Slider
 import com.wix.detox.espresso.ViewActionWithResult
 import com.wix.detox.espresso.common.SliderHelper
+import com.wix.detox.reactnative.ui.getAccessibilityLabel
 import org.hamcrest.Matcher
 import org.hamcrest.Matchers
 import org.hamcrest.Matchers.allOf
@@ -47,7 +48,7 @@ private class CommonAttributes {
     fun get(json: JSONObject, view: View) {
         getId(json, view)
         getVisibility(json, view)
-        getContentDescription(json, view)
+        getAccessibilityLabel(json, view)
         getAlpha(json, view)
         getElevation(json, view)
         getHeight(json, view)
@@ -66,8 +67,8 @@ private class CommonAttributes {
         json.put("visible", view.getLocalVisibleRect(Rect()))
     }
 
-    private fun getContentDescription(json: JSONObject, view: View) =
-            view.contentDescription?.let {
+    private fun getAccessibilityLabel(json: JSONObject, view: View) =
+            view.getAccessibilityLabel()?.let {
                 json.put("label", it)
             }
 

package/android/detox/src/full/java/com/wix/detox/espresso/matcher/ViewMatchers.kt

@@ -8,17 +8,20 @@ import androidx.test.espresso.matcher.BoundedMatcher
 import androidx.test.espresso.matcher.ViewMatchers
 import androidx.test.espresso.matcher.ViewMatchers.withEffectiveVisibility
 import com.wix.detox.espresso.common.SliderHelper
-import org.hamcrest.BaseMatcher
-import org.hamcrest.Description
-import org.hamcrest.Matcher
-import org.hamcrest.Matchers.allOf
-import org.hamcrest.TypeSafeMatcher
+import org.hamcrest.*
+import org.hamcrest.Matchers.*
 import kotlin.math.abs
 
 /*
  * An extension of [androidx.test.espresso.matcher.ViewMatchers].
  */
 
+fun withAccessibilityLabel(text: String) =
+    WithAccessibilityLabelMatcher(`is`(text))
+
+fun withShallowAccessibilityLabel(label: String): Matcher<View>
+    = anyOf(ViewMatchers.withContentDescription(label), ViewMatchers.withText(label))
+
 fun isOfClassName(className: String): Matcher<View> {
     try {
         val cls = Class.forName(className)

package/android/detox/src/full/java/com/wix/detox/espresso/matcher/WithAccessibilityLabelMatcher.kt

@@ -0,0 +1,23 @@
+package com.wix.detox.espresso.matcher
+
+import android.view.View
+import com.wix.detox.reactnative.ui.getAccessibilityLabel
+import org.hamcrest.Description
+import org.hamcrest.Matcher
+import org.hamcrest.TypeSafeDiagnosingMatcher
+
+class WithAccessibilityLabelMatcher(private val textMatcher: Matcher<String>): TypeSafeDiagnosingMatcher<View>() {
+    override fun matchesSafely(view: View, mismatchDescription: Description): Boolean =
+        view.getAccessibilityLabel().let { contentDescription ->
+            return textMatcher.matches(contentDescription).also { matched ->
+                if (!matched) {
+                    mismatchDescription.appendText("view.getAccessibilityLabel() ")
+                    textMatcher.describeMismatch(contentDescription, mismatchDescription)
+                }
+            }
+        }
+
+    override fun describeTo(description: Description) {
+        description.appendText("view.getAccessibilityLabel() ").appendDescriptionOf(textMatcher)
+    }
+}

package/android/detox/src/full/java/com/wix/detox/reactnative/ui/UIExtensions.kt

@@ -0,0 +1,37 @@
+package com.wix.detox.reactnative.ui
+
+import android.view.View
+import android.widget.TextView
+import com.wix.detox.common.traverseViewHierarchy
+import com.wix.detox.reactnative.utils.isReactNativeObject
+
+fun View.getAccessibilityLabel(
+    isReactNativeObjectFn: (Any) -> Boolean = { isReactNativeObject(it) }
+): CharSequence? =
+    if (isReactNativeObjectFn(this)) {
+        val subLabels = collectAccessibilityLabelsFromHierarchy(this)
+        if (subLabels.isEmpty()) null else subLabels.joinToString(" ")
+    } else {
+        getRawAccessibilityLabel(this)
+    }
+
+private fun collectAccessibilityLabelsFromHierarchy(
+    rootView: View,
+    subLabels: MutableList<CharSequence> = mutableListOf(),
+): List<CharSequence> {
+    traverseViewHierarchy(rootView) { view ->
+        getRawAccessibilityLabel(view)?.let { rawLabel ->
+            subLabels.add(rawLabel)
+            false
+        } ?: true
+
+    }
+    return subLabels
+}
+
+private fun getRawAccessibilityLabel(view: View): CharSequence? =
+    if (view.contentDescription != null) {
+        view.contentDescription
+    } else if (view is TextView) {
+        view.text
+    } else null

package/android/detox/src/full/java/com/wix/detox/reactnative/utils/RNUtils.kt

@@ -0,0 +1,6 @@
+package com.wix.detox.reactnative.utils
+
+private const val REACT_NATIVE_PACKAGE = "com.facebook.react"
+
+fun isReactNativeObject(obj: Any): Boolean =
+    obj.javaClass.canonicalName?.startsWith(REACT_NATIVE_PACKAGE) == true

package/android/detox/src/testFull/java/com/wix/detox/UTHelpers.kt

@@ -1,8 +1,20 @@
 package com.wix.detox
 
+import android.view.View
+import android.view.ViewGroup
+import org.mockito.ArgumentMatchers.eq
+import org.mockito.kotlin.whenever
 import java.util.concurrent.ExecutorService
 import java.util.concurrent.TimeUnit
 
 object UTHelpers {
     fun yieldToOtherThreads(executor: ExecutorService) = executor.awaitTermination(100L, TimeUnit.MILLISECONDS)
+
+    fun mockViewHierarchy(parent: ViewGroup, vararg children: View) {
+        whenever(parent.childCount).thenReturn(children.size)
+
+        children.forEachIndexed { index, view ->
+            whenever(parent.getChildAt(eq(index))).thenReturn(view)
+        }
+    }
 }

package/android/detox/src/testFull/java/com/wix/detox/common/UIExtensionsTest.kt

@@ -0,0 +1,107 @@
+package com.wix.detox.common
+
+import android.view.View
+import android.view.ViewGroup
+import android.widget.TextView
+import com.wix.detox.UTHelpers.mockViewHierarchy
+import com.wix.detox.reactnative.ui.getAccessibilityLabel
+import org.assertj.core.api.Assertions
+import org.junit.Test
+import org.junit.runner.RunWith
+import org.mockito.kotlin.doReturn
+import org.mockito.kotlin.mock
+import org.mockito.kotlin.whenever
+import org.robolectric.RobolectricTestRunner
+
+@RunWith(RobolectricTestRunner::class)
+class UIExtensionsTest {
+    private val alwaysReactNativeObjFn: (Any) -> Boolean = { true }
+    private val neverReactNativeObjFn: (Any) -> Boolean = { false }
+
+    private fun withContentDescription(value: String, v: View) { whenever(v.contentDescription).doReturn(value) }
+    private fun withText(value: String, v: TextView) { whenever(v.text).doReturn(value) }
+
+    @Test
+    fun `should return accessibility label according to content-description`() {
+        val view: View = mock()
+
+        val contentDescription = "content-description-mock"
+        withContentDescription(contentDescription, view)
+
+        val label = view.getAccessibilityLabel()
+        Assertions.assertThat(label).isEqualTo(contentDescription)
+    }
+
+    @Test
+    fun `should return accessibility label according to children's content-description, recursively`() {
+        val contentDescription1st = "cd.1"
+        val contentDescription2nd = "cd.2"
+        val expectedLabel = "$contentDescription1st $contentDescription2nd"
+
+
+        val parent: ViewGroup = mock()
+        val sibling1: ViewGroup = mock()
+        val sibling2: ViewGroup = mock<ViewGroup>().also {
+            withContentDescription(contentDescription2nd, it)
+        }
+        val grandchild: View = mock<View>().also {
+            withContentDescription(contentDescription1st, it)
+        }
+
+        mockViewHierarchy(parent, sibling1, sibling2)
+        mockViewHierarchy(sibling1, grandchild)
+
+        val label = parent.getAccessibilityLabel(alwaysReactNativeObjFn)
+        Assertions.assertThat(label).isEqualTo(expectedLabel)
+    }
+
+    @Test
+    fun `should return accessibility label according to children's text, on top of label`() {
+        val text = "some mocked text"
+
+        val parent: ViewGroup = mock()
+        val grandchild: TextView = mock<TextView>().also {
+            withText(text, it)
+        }
+        mockViewHierarchy(parent, grandchild)
+
+        val label = parent.getAccessibilityLabel(alwaysReactNativeObjFn)
+        Assertions.assertThat(label).isEqualTo(text)
+    }
+
+    @Test
+    fun `should not return accessibility label if content description not set in view nor its descendants`() {
+        val parent: ViewGroup = mock()
+        val child: View = mock()
+
+        mockViewHierarchy(parent, child)
+
+        val label = parent.getAccessibilityLabel(alwaysReactNativeObjFn)
+        Assertions.assertThat(label).isNull()
+    }
+
+    @Test
+    fun `should not return accessibility label based on children for non-RN views`() {
+        val childContentDescription = "content-description-mock"
+
+        val parent: ViewGroup = mock()
+        val child: View = mock<View>().also {
+            withContentDescription(childContentDescription, it)
+        }
+        mockViewHierarchy(parent, child)
+
+        val label = parent.getAccessibilityLabel(neverReactNativeObjFn)
+        Assertions.assertThat(label).isNull()
+    }
+
+    @Test
+    fun `should return accessibility label for non-RN views`() {
+        val view: View = mock()
+
+        val contentDescription = "content-description-mock"
+        withContentDescription(contentDescription, view)
+
+        val label = view.getAccessibilityLabel(neverReactNativeObjFn)
+        Assertions.assertThat(label).isEqualTo(contentDescription)
+    }
+}

package/android/detox/src/testFull/java/com/wix/detox/espresso/action/GetAttributesActionTest.kt

@@ -6,6 +6,7 @@ import android.widget.ProgressBar
 import android.widget.TextView
 import com.facebook.react.views.slider.ReactSlider
 import com.google.android.material.slider.Slider
+import com.wix.detox.reactnative.ui.getAccessibilityLabel
 import org.assertj.core.api.Assertions.assertThat
 import org.json.JSONObject
 import org.junit.Before
@@ -32,7 +33,7 @@ class GetAttributesActionTest {
     private fun givenNoViewTag() = givenViewTag(null)
     private fun givenVisibility(value: Int) { whenever(view.visibility).doReturn(value) }
     private fun givenVisibilityRectAvailability(value: Boolean) { whenever(view.getLocalVisibleRect(any())).doReturn(value) }
-    private fun givenContentDescription(value: String) { whenever(view.contentDescription).doReturn(value) }
+    private fun givenAccessibilityLabel(value: String) { whenever(view.getAccessibilityLabel()).doReturn(value) }
 
     private fun perform(v: View = view): JSONObject {
         uut.perform(null, v)
@@ -110,16 +111,16 @@ class GetAttributesActionTest {
     }
 
     @Test
-    fun `should return label according to content-description`() {
-        val contentDescription = "content-description-mock"
-        givenContentDescription(contentDescription)
+    fun `should return label according to accessibilityLabel extension`() {
+        val accessibilityLabel = "label-mock"
+        givenAccessibilityLabel(accessibilityLabel)
 
         val resultJson = perform()
-        assertThat(resultJson.opt("label")).isEqualTo(contentDescription)
+        assertThat(resultJson.opt("label")).isEqualTo(accessibilityLabel)
     }
 
     @Test
-    fun `should not return label if content description no set`() {
+    fun `should not return label if accessibility label is not available`() {
         val resultJson = perform()
         assertThat(resultJson.opt("label")).isNull()
     }

package/android/detox/src/testFull/java/com/wix/detox/espresso/matcher/ViewAtIndexMatcherSpec.kt

@@ -3,7 +3,6 @@ package com.wix.detox.espresso.matcher
 import android.view.View
 import org.hamcrest.Description
 import org.hamcrest.Matcher
-import org.hamcrest.Matchers
 import org.mockito.kotlin.mock
 import org.mockito.kotlin.verify
 import org.mockito.kotlin.whenever
@@ -28,7 +27,7 @@ object ViewAtIndexMatcherSpec: Spek({
                 uut.describeTo(description)
                 verify(description).appendText("View at index #0, of those matching MATCHER(innerMatcher description)")
             }
-            
+
             it("should append a valid description for index≥0") {
                 val uut = ViewAtIndexMatcher(7, innerMatcher)
                 uut.describeTo(description)

package/index.d.ts

@@ -331,6 +331,7 @@ declare global {
             binaryPath: string;
             bundleId?: string;
             build?: string;
+            start?: string;
             launchArgs?: Record<string, any>;
         }
 
@@ -339,6 +340,7 @@ declare global {
             binaryPath: string;
             bundleId?: string;
             build?: string;
+            start?: string;
             testBinaryPath?: string;
             launchArgs?: Record<string, any>;
             /**
@@ -624,9 +626,8 @@ declare global {
 
         interface Device {
             /**
-             * Holds the environment-unique ID of the device - namely, the adb ID on Android (e.g. emulator-5554) and the Mac-global simulator UDID on iOS,
+             * Holds the environment-unique ID of the device, namely, the adb ID on Android (e.g. emulator-5554) and the Mac-global simulator UDID on iOS -
              * as used by simctl (e.g. AAAAAAAA-BBBB-CCCC-DDDD-EEEEEEEEEEEE).
-             *
              */
             id: string;
             /**
@@ -1120,39 +1121,39 @@ declare global {
              * expectation with a `not` expects the view's visible area to be smaller than N%.
              * @param pct optional integer ranging from 1 to 100, indicating how much percent of the view should be
              *  visible to the user to be accepted.
-             * @example await expect(element(by.id('UniqueId204'))).toBeVisible(35);
+             * @example await expect(element(by.id('mainTitle'))).toBeVisible(35);
              */
             toBeVisible(pct?: number): R;
 
             /**
              * Negate the expectation.
-             * @example await expect(element(by.id('UniqueId205'))).not.toBeVisible();
+             * @example await expect(element(by.id('cancelButton'))).not.toBeVisible();
              */
             not: this;
 
             /**
              * Expect the view to not be visible.
-             * @example await expect(element(by.id('UniqueId205'))).toBeNotVisible();
+             * @example await expect(element(by.id('cancelButton'))).toBeNotVisible();
              * @deprecated Use `.not.toBeVisible()` instead.
              */
             toBeNotVisible(): R;
 
             /**
              * Expect the view to exist in the UI hierarchy.
-             * @example await expect(element(by.id('UniqueId205'))).toExist();
+             * @example await expect(element(by.id('okButton'))).toExist();
              */
             toExist(): R;
 
             /**
              * Expect the view to not exist in the UI hierarchy.
-             * @example await expect(element(by.id('RandomJunk959'))).toNotExist();
+             * @example await expect(element(by.id('cancelButton'))).toNotExist();
              * @deprecated Use `.not.toExist()` instead.
              */
             toNotExist(): R;
 
             /**
              * Expect the view to be focused.
-             * @example await expect(element(by.id('loginInput'))).toBeFocused();
+             * @example await expect(element(by.id('emailInput'))).toBeFocused();
              */
             toBeFocused(): R;
 
@@ -1166,21 +1167,23 @@ declare global {
             /**
              * In React Native apps, expect UI component of type <Text> to have text.
              * In native iOS apps, expect UI elements of type UIButton, UILabel, UITextField or UITextViewIn to have inputText with text.
-             * @example await expect(element(by.id('UniqueId204'))).toHaveText('I contain some text');
+             * @example await expect(element(by.id('mainTitle'))).toHaveText('Welcome back!);
              */
             toHaveText(text: string): R;
 
             /**
-             * It searches by accessibilityLabel on iOS, or by contentDescription on Android.
-             * In React Native it can be set for both platforms by defining an accessibilityLabel on the view.
-             * @example await expect(element(by.id('UniqueId204'))).toHaveLabel('Done');
+             * Expects a specific accessibilityLabel, as specified via the `accessibilityLabel` prop in React Native.
+             * On the native side (in both React Native and pure-native apps), that is equivalent to `accessibilityLabel`
+             * on iOS and contentDescription on Android. Refer to Detox's documentation in order to learn about caveats
+             * with accessibility-labels in React Native apps.
+             * @example await expect(element(by.id('submitButton'))).toHaveLabel('Submit');
              */
             toHaveLabel(label: string): R;
 
             /**
              * In React Native apps, expect UI component to have testID with that id.
              * In native iOS apps, expect UI element to have accessibilityIdentifier with that id.
-             * @example await expect(element(by.text('I contain some text'))).toHaveId('UniqueId204');
+             * @example await expect(element(by.text('Submit'))).toHaveId('submitButton');
              */
             toHaveId(id: string): R;
 
@@ -1193,7 +1196,7 @@ declare global {
 
             /**
              * Expect components like a Switch to have a value ('0' for off, '1' for on).
-             * @example await expect(element(by.id('UniqueId533'))).toHaveValue('0');
+             * @example await expect(element(by.id('temperatureDial'))).toHaveValue('25');
              */
             toHaveValue(value: any): R;
 
@@ -1210,7 +1213,7 @@ declare global {
             /**
              * This API polls using the given expectation continuously until the expectation is met. Use manual synchronization with waitFor only as a last resort.
              * NOTE: Every waitFor call must set a timeout using withTimeout(). Calling waitFor without setting a timeout will do nothing.
-             * @example await waitFor(element(by.id('UniqueId336'))).toExist().withTimeout(2000);
+             * @example await waitFor(element(by.id('bigButton'))).toExist().withTimeout(2000);
              */
             (element: NativeElement): Expect<WaitFor>;
         }
@@ -1218,13 +1221,13 @@ declare global {
         interface WaitFor {
             /**
              * Waits for the condition to be met until the specified time (millis) have elapsed.
-             * @example await waitFor(element(by.id('UniqueId336'))).toExist().withTimeout(2000);
+             * @example await waitFor(element(by.id('bigButton'))).toExist().withTimeout(2000);
              */
             withTimeout(millis: number): Promise<void>;
 
             /**
              * Performs the action repeatedly on the element until an expectation is met
-             * @example await waitFor(element(by.text('Text5'))).toBeVisible().whileElement(by.id('ScrollView630')).scroll(50, 'down');
+             * @example await waitFor(element(by.text('Item #5'))).toBeVisible().whileElement(by.id('itemsList')).scroll(50, 'down');
              */
             whileElement(by: NativeMatcher): NativeElement & WaitFor;
 
@@ -1436,7 +1439,7 @@ declare global {
         interface WebExpect<R = Promise<void>> {
             /**
              * Negate the expectation.
-             * @example await expect(web.element(by.web.id('UniqueId205'))).not.toExist();
+             * @example await expect(web.element(by.web.id('sessionTimeout'))).not.toExist();
              */
             not: this;
 
@@ -1444,13 +1447,13 @@ declare global {
              * Expect the element content to have the `text` supplied
              * @param text expected to be on the element content
              * @example
-             * await expect(web.element(by.web.id('UniqueId205'))).toHaveText('ExactText');
+             * await expect(web.element(by.web.id('checkoutButton'))).toHaveText('Proceed to check out');
              */
             toHaveText(text: string): R;
 
             /**
              * Expect the view to exist in the webview DOM tree.
-             * @example await expect(web.element(by.web.id('UniqueId205'))).toExist();
+             * @example await expect(web.element(by.web.id('submitButton'))).toExist();
              */
             toExist(): R;
         }
@@ -1649,7 +1652,9 @@ declare global {
              */
             text?: string;
             /**
-             * The label of the element. Matches accessibilityLabel for ios, and contentDescription for android.
+             * The label of the element. Largely matches accessibilityLabel for ios, and contentDescription for android.
+             * Refer to Detox's documentation (`toHaveLabel()` subsection) in order to learn about caveats associated with
+             * this property in React Native apps.
              */
             label?: string;
             /**

package/local-cli/cli.js

@@ -12,7 +12,7 @@ const { isErrorAlreadyLogged } = require('./utils/cliErrorHandling');
 yargs
   .scriptName('detox')
   .parserConfiguration({
-    'boolean-negation': false,
+    'boolean-negation': true,
     'camel-case-expansion': false,
     'dot-notation': false,
     'duplicate-arguments-array': false,

package/local-cli/init.js

@@ -93,13 +93,13 @@ function createDefaultConfigurations() {
       'android.debug': {
         type: 'android.apk',
         binaryPath: 'android/app/build/outputs/apk/debug/app-debug.apk',
-        build: 'cd android ; ./gradlew assembleDebug assembleAndroidTest -DtestBuildType=debug ; cd -',
+        build: 'cd android && ./gradlew assembleDebug assembleAndroidTest -DtestBuildType=debug',
         reversePorts: [8081],
       },
       'android.release': {
         type: 'android.apk',
         binaryPath: 'android/app/build/outputs/apk/release/app-release.apk',
-        build: 'cd android ; ./gradlew assembleRelease assembleAndroidTest -DtestBuildType=release ; cd -',
+        build: 'cd android && ./gradlew assembleRelease assembleAndroidTest -DtestBuildType=release',
       },
     },
     devices: {

package/local-cli/start.js

@@ -0,0 +1,49 @@
+const _ = require('lodash');
+
+const detox = require('../internals');
+
+const AppStartCommand = require('./startCommand/AppStartCommand');
+
+module.exports.command = 'start';
+module.exports.desc = 'Run app "start" scripts inside the selected configuration';
+module.exports.builder = {
+  C: {
+    alias: 'config-path',
+    describe: 'Specify Detox config file path. If not supplied, Detox searches for .detoxrc[.js] or "detox" section in package.json',
+  },
+  c: {
+    alias: ['configuration'],
+    describe:
+      'Select a local configuration from your defined configurations to extract the app "start" scripts from. If not supplied, and there\'s only one configuration, Detox will default to it',
+  },
+  f: {
+    alias: 'force',
+    describe: 'Ignore errors from the "start" scripts and proceed',
+    boolean: true,
+  }
+};
+
+module.exports.handler = async function start(argv) {
+  const { apps: appsConfig } = await detox.resolveConfig({ argv });
+  const startCommands = _(appsConfig)
+    .values()
+    .map(app => app.start)
+    .filter(Boolean)
+    .map(cmd => new AppStartCommand({
+      cmd,
+      passthrough: argv['--'],
+      forceSpawn: argv.force,
+    }))
+    .value();
+
+  if (startCommands.length) {
+    try {
+      await Promise.all(startCommands.map(c => c.execute()));
+    } catch (e) {
+      await Promise.allSettled(startCommands.map(c => c.stop()));
+      throw e;
+    }
+  } else {
+    detox.log.warn('No "start" commands were found in the app configs.');
+  }
+};

package/local-cli/startCommand/AppStartCommand.js

@@ -0,0 +1,65 @@
+const execa = require('execa');
+
+const detox = require('../../internals');
+const { DetoxRuntimeError } = require('../../src/errors');
+const Deferred = require('../../src/utils/Deferred');
+const log = detox.log.child({ cat: ['lifecycle', 'cli'] });
+
+class AppStartCommand {
+  constructor({ cmd, passthrough = [], forceSpawn = false }) {
+    this._id = Math.random();
+    this._cmd = cmd;
+    this._passthrough = passthrough;
+    this._forceSpawn = forceSpawn;
+
+    this._cpHandle = null;
+    this._cpDeferred = new Deferred();
+  }
+
+  execute() {
+    const cmd = [this._cmd, ...this._passthrough].join(' ');
+
+    log.info.begin({ id: this._id }, cmd);
+
+    const onEnd = (msg, code, signal) => {
+      log.trace.end({ id: this._id, code, signal }, msg);
+      this._cpDeferred.resolve();
+    };
+
+    const onError = (msg, code, signal) => {
+      const logLevel = this._forceSpawn ? 'warn' : 'error';
+      log[logLevel].end({ id: this._id, code, signal }, msg);
+      if (this._forceSpawn) {
+        this._cpDeferred.resolve();
+      } else {
+        this._cpDeferred.reject(new DetoxRuntimeError(msg));
+      }
+    };
+
+    this._cpHandle = execa.command(cmd, { stdio: 'inherit', shell: true });
+    this._cpHandle.on('error', onError);
+    this._cpHandle.on('exit', (code, signal) => {
+      const reason = code == null ? `signal ${signal}` : `code ${code}`;
+      const msg = `Command exited with ${reason}: ${cmd}`;
+      if (signal || code === 0) {
+        onEnd(msg, code, signal);
+      } else {
+        onError(msg, code, signal);
+      }
+
+      this._cpHandle = null;
+    });
+
+    return this._cpDeferred.promise;
+  }
+
+  async stop() {
+    if (this._cpHandle) {
+      this._cpHandle.kill();
+    }
+
+    return this._cpDeferred.promise;
+  }
+}
+
+module.exports = AppStartCommand;

package/local-cli/testCommand/TestRunnerCommand.js

@@ -9,6 +9,8 @@ const log = detox.log.child({ cat: ['lifecycle', 'cli'] });
 const { printEnvironmentVariables, prependNodeModulesBinToPATH } = require('../../src/utils/envUtils');
 const { toSimplePath } = require('../../src/utils/pathUtils');
 const { escapeSpaces, useForwardSlashes } = require('../../src/utils/shellUtils');
+const sleep = require('../../src/utils/sleep');
+const AppStartCommand = require('../startCommand/AppStartCommand');
 const { markErrorAsLogged } = require('../utils/cliErrorHandling');
 
 const TestRunnerError = require('./TestRunnerError');
@@ -23,11 +25,14 @@ class TestRunnerCommand {
     const cliConfig = opts.config.cli;
     const deviceConfig = opts.config.device;
     const runnerConfig = opts.config.testRunner;
+    const appsConfig = opts.config.apps;
 
     this._argv = runnerConfig.args;
     this._retries = runnerConfig.retries;
     this._envHint = this._buildEnvHint(opts.env);
+    this._startCommands = this._prepareStartCommands(appsConfig, cliConfig);
     this._envFwd = {};
+
     if (runnerConfig.forwardEnv) {
       this._envFwd = this._buildEnvOverride(cliConfig, deviceConfig);
       Object.assign(this._envHint, this._envFwd);
@@ -38,6 +43,15 @@ class TestRunnerCommand {
     let runsLeft = 1 + this._retries;
     let launchError = null;
 
+    if (this._startCommands.length > 0) {
+      try {
+        await Promise.race([sleep(1000), ...this._startCommands.map(cmd => cmd.execute())]);
+      } catch (e) {
+        await Promise.allSettled(this._startCommands.map(cmd => cmd.stop()));
+        throw e;
+      }
+    }
+
     do {
       try {
         await this._spawnTestRunner();
@@ -67,6 +81,8 @@ class TestRunnerCommand {
       }
     } while (launchError && runsLeft > 0);
 
+    await Promise.allSettled(this._startCommands.map(cmd => cmd.stop()));
+
     if (launchError) {
       throw launchError;
     }
@@ -80,6 +96,19 @@ class TestRunnerCommand {
       .value();
   }
 
+  _prepareStartCommands(appsConfig, cliConfig) {
+    if (`${cliConfig.start}` === 'false') {
+      return [];
+    }
+
+    return _.values(appsConfig)
+      .filter(app => app.start)
+      .map(app => new AppStartCommand({
+        cmd: app.start,
+        forceSpawn: cliConfig.start === 'force',
+      }));
+  }
+
   /**
    * @param {DetoxInternals.CLIConfig} cliConfig
    * @param {Detox.DetoxDeviceConfig} deviceConfig

package/local-cli/testCommand/builder.js

@@ -28,6 +28,11 @@ module.exports = {
     describe: 'Reuse existing installed app (do not delete + reinstall) for a faster run.',
     boolean: true,
   },
+  start: {
+    group: 'Execution:',
+    describe: 'Run app "start" scripts before running the tests. Use --no-start to disable that, and --start=force to ignore errors.',
+    default: true,
+  },
   u: {
     alias: 'cleanup',
     group: 'Execution:',

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "detox",
   "description": "E2E tests and automation for mobile",
-  "version": "20.4.0",
+  "version": "20.6.0",
   "bin": {
     "detox": "local-cli/cli.js"
   },
@@ -63,6 +63,7 @@
     "caf": "^15.0.1",
     "chalk": "^2.4.2",
     "child-process-promise": "^2.2.0",
+    "execa": "^5.1.1",
     "find-up": "^4.1.0",
     "fs-extra": "^4.0.2",
     "funpermaproxy": "^1.1.0",
@@ -199,5 +200,5 @@
       }
     }
   },
-  "gitHead": "9329070b1dca0702015f44b3e75dd11f70651a5b"
+  "gitHead": "03e23e76b54f1e7de70495e0ec8a8db45872b0e6"
 }

package/src/android/core/NativeMatcher.js

@@ -1,27 +1,44 @@
+const { inspect } = require('util');
+
+const { DetoxRuntimeError } = require('../../errors');
 const invoke = require('../../invoke');
 const DetoxMatcherApi = require('../espressoapi/DetoxMatcher');
 
 class NativeMatcher {
+  static _assertMatcher(matcher) {
+    if (!(matcher instanceof NativeMatcher)) {
+      throw new DetoxRuntimeError({ message: `Expected a matcher, got: ${inspect(matcher)}` });
+    }
+  }
+
   constructor(call) {
     this._call = call || null;
   }
 
   withAncestor(matcher) {
+    NativeMatcher._assertMatcher(matcher);
+
     const call = invoke.callDirectly(DetoxMatcherApi.matcherWithAncestor(this, matcher));
     return new NativeMatcher(call);
   }
 
   withDescendant(matcher) {
+    NativeMatcher._assertMatcher(matcher);
+
     const call = invoke.callDirectly(DetoxMatcherApi.matcherWithDescendant(this, matcher));
     return new NativeMatcher(call);
   }
 
   and(matcher) {
+    NativeMatcher._assertMatcher(matcher);
+
     const call = invoke.callDirectly(DetoxMatcherApi.matcherForAnd(this, matcher));
     return new NativeMatcher(call);
   }
 
   or(matcher) {
+    NativeMatcher._assertMatcher(matcher);
+
     const call = invoke.callDirectly(DetoxMatcherApi.matcherForOr(this, matcher));
     return new NativeMatcher(call);
   }

package/src/android/espressoapi/DetoxMatcher.js

@@ -26,6 +26,30 @@ class DetoxMatcher {
     };
   }
 
+  static matcherForAccessibilityLabel(label) {
+    if (typeof label !== "string") throw new Error("label should be a string, but got " + (label + (" (" + (typeof label + ")"))));
+    return {
+      target: {
+        type: "Class",
+        value: "com.wix.detox.espresso.DetoxMatcher"
+      },
+      method: "matcherForAccessibilityLabel",
+      args: [label]
+    };
+  }
+
+  static matcherForShallowAccessibilityLabel(label) {
+    if (typeof label !== "string") throw new Error("label should be a string, but got " + (label + (" (" + (typeof label + ")"))));
+    return {
+      target: {
+        type: "Class",
+        value: "com.wix.detox.espresso.DetoxMatcher"
+      },
+      method: "matcherForShallowAccessibilityLabel",
+      args: [label]
+    };
+  }
+
   static matcherForContentDescription(contentDescription) {
     if (typeof contentDescription !== "string") throw new Error("contentDescription should be a string, but got " + (contentDescription + (" (" + (typeof contentDescription + ")"))));
     return {

package/src/android/matchers/index.js

@@ -2,9 +2,9 @@ const native = require('./native');
 const web = require('./web');
 
 module.exports = {
-  accessibilityLabel: (value) => new native.LabelMatcher(value),
   id: (value) => new native.IdMatcher(value),
-  label: (value) => new native.LabelMatcher(value),
+  label: (value) => new native.ShallowLabelMatcher(value),
+  accessibilityLabel: (value) => new native.ShallowLabelMatcher(value),
   text: (value) => new native.TextMatcher(value),
   traits: (value) => new native.TraitsMatcher(value),
   type: (value) => new native.TypeMatcher(value),

package/src/android/matchers/native.js

@@ -6,7 +6,14 @@ const DetoxMatcherApi = require('../espressoapi/DetoxMatcher');
 class LabelMatcher extends NativeMatcher {
   constructor(value) {
     super();
-    this._call = invoke.callDirectly(DetoxMatcherApi.matcherForContentDescription(value));
+    this._call = invoke.callDirectly(DetoxMatcherApi.matcherForAccessibilityLabel(value));
+  }
+}
+
+class ShallowLabelMatcher extends NativeMatcher {
+  constructor(value) {
+    super();
+    this._call = invoke.callDirectly(DetoxMatcherApi.matcherForShallowAccessibilityLabel(value));
   }
 }
 
@@ -90,6 +97,7 @@ class SliderPositionMatcher extends NativeMatcher {
 
 module.exports = {
   LabelMatcher,
+  ShallowLabelMatcher,
   IdMatcher,
   TypeMatcher,
   TraitsMatcher,

package/src/configuration/collectCliConfig.js

@@ -55,6 +55,7 @@ function collectCliConfig({ argv }) {
     useCustomLogger: asBoolean(get('use-custom-logger')),
     retries: asNumber(get('retries')),
     inspectBrk: asBoolean(get('inspect-brk')),
+    start: get('start'),
   }, _.isUndefined);
 }
 

package/Detox-android/com/wix/detox/20.4.0/detox-20.4.0-javadoc.jar.md5

@@ -1 +0,0 @@
-fe1f11c2f7311ae0f6b13926808a59fc

package/Detox-android/com/wix/detox/20.4.0/detox-20.4.0-javadoc.jar.sha1

@@ -1 +0,0 @@
-bd54a4027638a599254b2df73919dd4fc2633ec2

package/Detox-android/com/wix/detox/20.4.0/detox-20.4.0-javadoc.jar.sha256

@@ -1 +0,0 @@
-7f7ab53c44e53bb959746e8ccc107e3f04d2aca31ec75fb544891db0eb91a476

package/Detox-android/com/wix/detox/20.4.0/detox-20.4.0-javadoc.jar.sha512

@@ -1 +0,0 @@
-83af81079557e46d8b995f28b6e8ed8a221d02e9d6319146d978b84df530ff6289806c6b9c13de94cb5023948a986ee8dc8a4dfc15ab8c683af1cb6013e4e1a8

package/Detox-android/com/wix/detox/20.4.0/detox-20.4.0-sources.jar.md5

@@ -1 +0,0 @@
-1493e043853c3f2a42d0d63062b796f1

package/Detox-android/com/wix/detox/20.4.0/detox-20.4.0-sources.jar.sha1

@@ -1 +0,0 @@
-a2da124a011cf479474605ddefd629fc192498b4

package/Detox-android/com/wix/detox/20.4.0/detox-20.4.0-sources.jar.sha256

@@ -1 +0,0 @@
-8d64a4b32323c64dcec482f322d19233577ffc5fe3895e3ca30d9cb220504409

package/Detox-android/com/wix/detox/20.4.0/detox-20.4.0-sources.jar.sha512

@@ -1 +0,0 @@
-2bb0aaf9f7232f18adcebd3d1fc1424d1d8f1d47892663f962030ef7db1a02eb7943844aa69f14b4ebeb01d0dd562dc0420fb0ff7152a38ca44e1a525a58d745

package/Detox-android/com/wix/detox/20.4.0/detox-20.4.0.aar.md5

@@ -1 +0,0 @@
-e8ad50ff5afce32b3cb728f837917c3a

package/Detox-android/com/wix/detox/20.4.0/detox-20.4.0.aar.sha1

@@ -1 +0,0 @@
-8f1738000005765fd1d4746e5f2d85c766dd591f

package/Detox-android/com/wix/detox/20.4.0/detox-20.4.0.aar.sha256

@@ -1 +0,0 @@
-da1efa26b94b52cdbb831470e5753e0982bbe5ec1c861f8965a7347199e67b8b

package/Detox-android/com/wix/detox/20.4.0/detox-20.4.0.aar.sha512

@@ -1 +0,0 @@
-9940e5dd655923d057b095817edc22c952105b1518ff02f1316cfd50be45999127e8410eb9b22e95d155517f455a484b3a52f9533f6f40e3f1e9efbf49a5eaa9

package/Detox-android/com/wix/detox/20.4.0/detox-20.4.0.pom.md5

@@ -1 +0,0 @@
-a2316bed8a49f4fd9eb9658c90571244

package/Detox-android/com/wix/detox/20.4.0/detox-20.4.0.pom.sha1

@@ -1 +0,0 @@
-101c01798b6766fca29a04a0cfc4a236db6416fe

package/Detox-android/com/wix/detox/20.4.0/detox-20.4.0.pom.sha256

@@ -1 +0,0 @@
-cc58b9b38e7a2ea38be0e50f76895e2d01806142ea99293eab307482321586c6

package/Detox-android/com/wix/detox/20.4.0/detox-20.4.0.pom.sha512

@@ -1 +0,0 @@
-df4124c805c1232369779953fb57f1b8d8bb9ee0de3f3e66e72f33254422e2a39a8b76fdbbffef7dc8c796eefce26fbf85723f4e7a28c8b6591d2fe085b89e14