appium-espresso-driver 1.46.0

package/espresso-server/app/src/androidTest/java/io/appium/espressoserver/lib/helpers/ReflectionUtils.kt

@@ -0,0 +1,64 @@
+/*
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * See the NOTICE file distributed with this work for additional
+ * information regarding copyright ownership.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package io.appium.espressoserver.lib.helpers
+
+import io.appium.espressoserver.lib.handlers.exceptions.AppiumException
+import io.appium.espressoserver.lib.helpers.reflection.MethodUtils
+import java.lang.reflect.Field
+import java.lang.reflect.Method
+import kotlin.reflect.KProperty1
+import kotlin.reflect.full.declaredMemberProperties
+
+object ReflectionUtils {
+
+    fun extractMethod(clazz: Class<*>, methodName: String, vararg parameterTypes: Class<*>): Method {
+        try {
+            val result = clazz.getDeclaredMethod(methodName, *parameterTypes)
+            result.isAccessible = true
+            return result
+        } catch (e: NoSuchMethodException) {
+            throw AppiumException("Method '${methodName}' is not defined for class ${clazz.canonicalName}", e)
+        }
+    }
+
+    fun invokeStaticMethod(clazz: Class<*>, methodName: String, vararg providedParams: Any?): Any? =
+            MethodUtils.invokeStaticMethod(clazz, methodName, *providedParams)
+
+    fun invokeInstanceMethod(instance: Any, methodName: String, vararg providedParams: Any?): Any? =
+            MethodUtils.invokeMethod(instance, methodName, *providedParams)
+
+    fun invokeMethod(instance: Any?, method: Method, vararg providedParams: Any?): Any? =
+            method.invoke(instance, *providedParams)
+
+    fun extractField(clazz: Class<*>, fieldName: String, instance: Any?): Any? {
+        val field: Field = clazz.getDeclaredField(fieldName)
+        field.isAccessible = true
+        return field.get(instance)
+    }
+
+    fun extractDeclaredProperties(instance: Any): Map<String, Any?> {
+        return instance::class.declaredMemberProperties
+                .fold(mutableMapOf<String, Any?>()) { acc, prop ->
+                    try {
+                        @Suppress("UNCHECKED_CAST")
+                        acc[prop.name] = (prop as KProperty1<Any, Any?>).get(instance)
+                    } catch (ign: Exception) {
+                    }
+                    acc
+                }.toMap()
+    }
+}

package/espresso-server/app/src/androidTest/java/io/appium/espressoserver/lib/helpers/ScreenshotsHelper.kt

@@ -0,0 +1,59 @@
+/*
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * See the NOTICE file distributed with this work for additional
+ * information regarding copyright ownership.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package io.appium.espressoserver.lib.helpers
+
+import android.graphics.Bitmap
+import android.util.Base64
+import android.view.View
+
+import java.io.ByteArrayOutputStream
+import androidx.test.runner.screenshot.Screenshot
+import io.appium.espressoserver.lib.handlers.exceptions.AppiumException
+import io.appium.espressoserver.lib.handlers.exceptions.ElementNotVisibleException
+import io.appium.espressoserver.lib.handlers.exceptions.ScreenCaptureException
+import io.appium.espressoserver.lib.model.ViewElement
+
+class ScreenshotsHelper @JvmOverloads constructor(private val view: View? = null) {
+
+    /**
+     * Makes a screenshot of the particular view.
+     *
+     * @return the screenshot of the view as base-64 encoded string.
+     * @throws ElementNotVisibleException if the view has no visible area.
+     * @throws ScreenCaptureException if it is impossible to take a screenshot.
+     */
+    val screenshot: String
+        @Throws(AppiumException::class)
+        get() {
+            if (view != null && ViewElement(view).bounds.isEmpty) {
+                throw ElementNotVisibleException(
+                        String.format("Cannot get a screenshot of the invisible %s", view.javaClass.name))
+            }
+
+            val screenCap = if (view == null) Screenshot.capture() else Screenshot.capture(view)
+            val bitmapScreenCap = screenCap.bitmap
+            if (bitmapScreenCap == null || bitmapScreenCap.height == 0 || bitmapScreenCap.width == 0) {
+                throw ScreenCaptureException("Cannot capture a shot of the " +
+                        "${if (view == null) "current screen" else view.javaClass.name}. " +
+                        "Make sure none of the currently visible " +
+                        "views have FLAG_SECURE set and that it is possible to take a screenshot manually")
+            }
+            val outputStream = ByteArrayOutputStream()
+            bitmapScreenCap.compress(Bitmap.CompressFormat.PNG, 100, outputStream)
+            return Base64.encodeToString(outputStream.toByteArray(), Base64.DEFAULT)
+        }
+}

package/espresso-server/app/src/androidTest/java/io/appium/espressoserver/lib/helpers/StringHelpers.kt

@@ -0,0 +1,42 @@
+/*
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * See the NOTICE file distributed with this work for additional
+ * information regarding copyright ownership.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package io.appium.espressoserver.lib.helpers
+
+object StringHelpers {
+
+    @JvmStatic
+    fun abbreviate(str: String?, len: Int): String? {
+        return if (str != null && str.length > len) str.substring(0, len) + "\u2026" else str
+    }
+
+    fun isBlank(str: String?): Boolean {
+        return str == null || str.trim { it <= ' ' } == ""
+    }
+
+    private fun charSequenceToString(input: CharSequence?, replaceNull: Boolean): String? {
+        return input?.toString() ?: if (replaceNull) "" else null
+    }
+
+    fun charSequenceToNullableString(input: CharSequence?): String? {
+        return charSequenceToString(input, false)
+    }
+
+    fun charSequenceToNonNullString(input: CharSequence?): String {
+        return charSequenceToString(input, true)!!.toString()
+    }
+
+}

package/espresso-server/app/src/androidTest/java/io/appium/espressoserver/lib/helpers/ThreadHelpers.kt

@@ -0,0 +1,15 @@
+package io.appium.espressoserver.lib.helpers
+
+fun getThreadDump() : String {
+    val threadDetails = StringBuilder()
+    val activeCount = Thread.activeCount()
+    val threads = arrayOfNulls<Thread>(activeCount)
+    Thread.enumerate(threads)
+    for (thread in threads.filterNotNull()) {
+        threadDetails.append("\n\n ThreadName: ${thread.name}: State: ${thread.state}")
+        for (stackTraceElement in thread.stackTrace) {
+            threadDetails.append("\n\t\t$stackTraceElement")
+        }
+    }
+    return threadDetails.toString();
+}

package/espresso-server/app/src/androidTest/java/io/appium/espressoserver/lib/helpers/UiAutomationWrapper.kt

@@ -0,0 +1,48 @@
+/*
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * See the NOTICE file distributed with this work for additional
+ * information regarding copyright ownership.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package io.appium.espressoserver.lib.helpers
+
+import android.app.UiAutomation
+import android.app.UiAutomation.OnAccessibilityEventListener
+import androidx.test.platform.app.InstrumentationRegistry
+import androidx.test.uiautomator.UiDevice
+import io.appium.espressoserver.lib.helpers.ReflectionUtils.extractField
+import io.appium.espressoserver.lib.helpers.ReflectionUtils.extractMethod
+import io.appium.espressoserver.lib.helpers.ReflectionUtils.invokeMethod
+
+const val FIELD_ON_ACCESSIBILITY_EVENT_LISTENER = "mOnAccessibilityEventListener"
+
+object UiAutomationWrapper {
+    private val uia: UiAutomation
+    private val uiDevice: UiDevice
+        get() = UiDevice.getInstance(InstrumentationRegistry.getInstrumentation())
+
+    init {
+        uia = invokeMethod(uiDevice, extractMethod(UiDevice::class.java, "getUiAutomation")) as UiAutomation
+    }
+
+    var onAccessibilityEventListener: OnAccessibilityEventListener?
+        get() = try {
+            extractField(UiAutomationWrapper::class.java,
+                    FIELD_ON_ACCESSIBILITY_EVENT_LISTENER, uia) as OnAccessibilityEventListener?
+        } catch (e: Exception) {
+            /* mOnAccessibilityEventListener is no longer accessible on Android P */
+            null
+        }
+        set(listener) {
+            uia.setOnAccessibilityEventListener(listener)
+        }
+}

package/espresso-server/app/src/androidTest/java/io/appium/espressoserver/lib/helpers/ViewFinder.kt

@@ -0,0 +1,316 @@
+/*
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * See the NOTICE file distributed with this work for additional
+ * information regarding copyright ownership.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package io.appium.espressoserver.lib.helpers
+
+import android.content.Context
+
+import androidx.test.espresso.DataInteraction
+import androidx.test.espresso.EspressoException
+import androidx.test.espresso.PerformException
+import android.view.View
+import android.widget.AdapterView
+
+import org.hamcrest.Description
+import org.hamcrest.Matcher
+import org.hamcrest.Matchers
+import org.hamcrest.TypeSafeMatcher
+
+import java.util.ArrayList
+
+import io.appium.espressoserver.lib.handlers.exceptions.AppiumException
+import io.appium.espressoserver.lib.handlers.exceptions.InvalidSelectorException
+import io.appium.espressoserver.lib.handlers.exceptions.XPathLookupException
+import io.appium.espressoserver.lib.model.Strategy
+import io.appium.espressoserver.lib.viewaction.ViewGetter
+
+import androidx.test.core.app.ApplicationProvider.getApplicationContext
+import androidx.test.espresso.AppNotIdleException
+import androidx.test.espresso.Espresso.onData
+import androidx.test.espresso.Espresso.onView
+import androidx.test.espresso.assertion.ViewAssertions.matches
+import androidx.test.espresso.matcher.ViewMatchers.isDescendantOfA
+import androidx.test.espresso.matcher.ViewMatchers.isDisplayed
+import androidx.test.espresso.matcher.ViewMatchers.withClassName
+import androidx.test.espresso.matcher.ViewMatchers.withContentDescription
+import androidx.test.espresso.matcher.ViewMatchers.withId
+import androidx.test.espresso.matcher.ViewMatchers.withTagValue
+import androidx.test.espresso.matcher.ViewMatchers.withText
+import io.appium.espressoserver.lib.handlers.exceptions.InvalidElementStateException
+import io.appium.espressoserver.lib.model.toJsonMatcher
+import io.appium.espressoserver.lib.viewmatcher.withView
+import io.appium.espressoserver.lib.viewmatcher.withXPath
+import org.hamcrest.CoreMatchers.allOf
+import org.hamcrest.CoreMatchers.equalTo
+import org.hamcrest.CoreMatchers.`is`
+import org.hamcrest.Matchers.endsWith
+import org.hamcrest.Matchers.hasEntry
+import org.hamcrest.Matchers.instanceOf
+
+/**
+ * Helper methods to find elements based on locator strategies and selectors
+ */
+object ViewFinder {
+    private const val ID_PATTERN = "[\\S]+:id/[\\S]+"
+    private const val APP_NOT_IDLE_MESSAGE = "The application is expected to be in idle state in order for Espresso to interact with it. " +
+            "Review the threads dump below to know more on which entity is hogging the events loop "
+
+    /**
+     * Find one instance of an element that matches the locator criteria
+     *
+     * @param root     Parent view instance or null if the search is executed against the
+     * full hierarchy
+     * @param strategy Locator strategy (xpath, class name, etc...)
+     * @param selector Selector string
+     * @return
+     * @throws InvalidSelectorException
+     * @throws XPathLookupException
+     */
+    @Throws(AppiumException::class)
+    fun findBy(
+            root: View?, strategy: Strategy, selector: String): View? {
+        val viewInteractions = findAllBy(root, strategy, selector, true)
+        return if (viewInteractions.isEmpty()) {
+            null
+        } else viewInteractions[0]
+    }
+
+    /**
+     * Find all instances of an element that matches the locator criteria
+     *
+     * @param root     Parent view instance or null if the search is executed against the
+     * full hierarchy
+     * @param strategy Locator strategy (xpath, class name, etc...)
+     * @param selector Selector string
+     * @return
+     * @throws InvalidSelectorException
+     * @throws XPathLookupException
+     */
+    @Throws(AppiumException::class)
+    fun findAllBy(root: View?,
+                  strategy: Strategy, selector: String): List<View> {
+        return findAllBy(root, strategy, selector, false)
+    }
+
+    /**
+     * Returns the currently focused element or null if
+     * there is no such element
+     *
+     * @return focused element instance or null
+     */
+    fun findActive(): View? {
+        val views = getViews(null,
+                object : TypeSafeMatcher<View>() {
+                    override fun matchesSafely(item: View): Boolean {
+                        return item.isFocused
+                    }
+
+                    override fun describeTo(description: Description) {
+                        description.appendText("is focused")
+                    }
+                },
+                true)
+        return if (views.isEmpty()) {
+            null
+        } else views[0]
+    }
+
+    ///Find By different strategies
+    @Throws(AppiumException::class)
+    private fun findAllBy(root: View?, strategy: Strategy,
+                          selector: String, findOne: Boolean): List<View> {
+        @Suppress("NAME_SHADOWING") var selector = selector
+        var views: List<View>
+        when (strategy) {
+            Strategy.ID // with ID
+            -> {
+
+                // find id from target context
+                val context = getApplicationContext<Context>()
+                if (!selector.matches(ID_PATTERN.toRegex())) {
+                    selector = "${context.packageName}:id/$selector"
+                    AndroidLogger.info("Rewrote Id selector to '$selector'")
+                }
+                val id = context.resources.getIdentifier(selector, "Id", context.packageName)
+
+                views = getViews(root, withId(id), findOne)
+            }
+            Strategy.CLASS_NAME ->
+                // with class name
+                // TODO: improve this finder with instanceOf
+                views = getViews(root, withClassName(endsWith(selector)), findOne)
+            Strategy.TEXT ->
+                // with text
+                views = getViews(root, withText(selector), findOne)
+            Strategy.ACCESSIBILITY_ID -> {
+                views = getViews(root, withContentDescription(selector), findOne)
+
+                // If the item is not found on the screen, use 'onData' to try
+                // to scroll it into view and then locate it again
+                if (views.isEmpty() && canScrollToViewWithContentDescription(root, selector)) {
+                    views = getViews(root, withContentDescription(selector), findOne)
+                }
+            }
+            Strategy.XPATH ->
+                // If we're only looking for one item that matches xpath, pass it index 0 or else
+                // Espresso throws an AmbiguousMatcherException
+                views = if (findOne) {
+                    getViews(root, withXPath(root, selector, 0), true)
+                } else {
+                    getViews(root, withXPath(root, selector), false)
+                }
+            Strategy.VIEW_TAG -> views = getViews(root, withTagValue(allOf(instanceOf(String::class.java),
+                    equalTo(selector as Any))), findOne)
+            Strategy.DATAMATCHER -> {
+                val matcher = selector.toJsonMatcher()
+                views = try {
+                    getViewsFromDataInteraction(root, onData(matcher.matcher))
+                } catch (e: PerformException) {
+                    // Perform Exception means nothing was found. Return empty list
+                    emptyList()
+                }
+            }
+            Strategy.VIEWMATCHER -> {
+                val matcherJson = selector.toJsonMatcher()
+                views = try {
+                    @Suppress("UNCHECKED_CAST")
+                    getViewsFromViewMatcher(root, matcherJson.matcher as Matcher<View>)
+                } catch (e: PerformException) {
+                    // Perform Exception means nothing was found. Return empty list
+                    emptyList()
+                }
+            }
+            else -> throw InvalidSelectorException("Strategy is not implemented: ${strategy.strategyName}")
+        }
+
+        return views
+    }
+
+    /**
+     * Attempts to scroll to a view with the content description using onData
+     *
+     * @param contentDesc Content description
+     * @return
+     */
+    private fun canScrollToViewWithContentDescription(parentView: View?,
+                                                      contentDesc: String): Boolean {
+        try {
+            val dataInteraction = onData(
+                    hasEntry(Matchers.equalTo("contentDescription"), `is`(contentDesc))
+            )
+
+            // If the parentView provided is an AdapterView, set 'inAdapterView' so that the
+            // selector is restricted to the adapter subtree
+            if (parentView is AdapterView<*>) {
+                dataInteraction.inAdapterView(withView(parentView))
+            }
+            dataInteraction.check(matches(isDisplayed()))
+        } catch (e: Exception) {
+            return false
+        }
+
+        return true
+    }
+
+    private fun getViewsFromDataInteraction(
+            root: View?, dataInteraction: DataInteraction
+    ): List<View> {
+        // Defensive copy
+        var dataInteractionCopy = dataInteraction
+
+        // Look up the view hierarchy to find the closest ancestor AdapterView
+        var ancestorAdapterView = root
+        while (ancestorAdapterView != null && ancestorAdapterView !is AdapterView<*>) {
+            val parent = ancestorAdapterView.parent
+            ancestorAdapterView = parent as? View
+        }
+        ancestorAdapterView?.let {
+            dataInteractionCopy = dataInteractionCopy.inAdapterView(withView(it))
+        }
+
+        return listOf(ViewGetter().getView(dataInteractionCopy))
+    }
+
+    private fun getViewsFromViewMatcher(root: View?, matcher: Matcher<View>): List<View> {
+        val viewInteraction = if (root == null)
+            onView(matcher)
+        else
+            onView(allOf(isDescendantOfA(`is`(root)), matcher))
+        return listOf(ViewGetter().getView(viewInteraction))
+    }
+
+    private fun getViews(
+            root: View?, matcher: Matcher<View>, findOne: Boolean): List<View> {
+        // If it's just one view we want, return a singleton list
+        if (findOne) {
+            try {
+                val viewInteraction = if (root == null)
+                    onView(withIndex(matcher, 0))
+                else
+                    onView(allOf(isDescendantOfA(`is`(root)), withIndex(matcher, 0)))
+                return listOf(ViewGetter().getView(viewInteraction))
+            } catch (e: AppNotIdleException){
+                throw InvalidElementStateException(APP_NOT_IDLE_MESSAGE + getThreadDump(), e)
+            } catch (e: Exception) {
+                if (e is EspressoException) {
+                    return emptyList()
+                }
+                throw e
+            }
+        }
+
+        // If we want all views that match the criteria, start looking for ViewInteractions by
+        // index and add each match to the List. As soon as we find no match, break the loop
+        // and return the list
+        val viewInteractions = ArrayList<View>()
+        var i = 0
+        do {
+            try {
+                val viewInteraction = if (root == null)
+                    onView(withIndex(matcher, i++))
+                else
+                    onView(allOf(isDescendantOfA(`is`(root)), withIndex(matcher, i++)))
+                val view = ViewGetter().getView(viewInteraction)
+                viewInteractions.add(view)
+            } catch (e: AppNotIdleException){
+                throw InvalidElementStateException(APP_NOT_IDLE_MESSAGE + getThreadDump(), e)
+            } catch (e: Exception) {
+                if (e is EspressoException) {
+                    return viewInteractions
+                }
+                throw e
+            }
+
+        } while (i < Integer.MAX_VALUE)
+        return viewInteractions
+    }
+
+    private fun withIndex(matcher: Matcher<View>, index: Int): Matcher<View> {
+        return object : TypeSafeMatcher<View>() {
+            var currentIndex = 0
+
+            override fun describeTo(description: Description) {
+                description.appendText("with index: ")
+                description.appendValue(index)
+                matcher.describeTo(description)
+            }
+
+            public override fun matchesSafely(view: View): Boolean {
+                return matcher.matches(view) && currentIndex++ == index
+            }
+        }
+    }
+}

package/espresso-server/app/src/androidTest/java/io/appium/espressoserver/lib/helpers/XMLHelpers.kt

@@ -0,0 +1,56 @@
+/*
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * See the NOTICE file distributed with this work for additional
+ * information regarding copyright ownership.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package io.appium.espressoserver.lib.helpers
+
+import java.util.regex.Pattern
+
+object XMLHelpers {
+    // XML 1.0 Legal Characters (http://stackoverflow.com/a/4237934/347155)
+    // #x9 | #xA | #xD | [#x20-#xD7FF] | [#xE000-#xFFFD] | [#x10000-#x10FFFF]
+    private val XML10_PATTERN = Pattern.compile("[^" + "\u0009\r\n" +
+            "\u0020-\uD7FF" + "\uE000-\uFFFD" + "\ud800\udc00-\udbff\udfff" + "]")
+    // https://stackoverflow.com/questions/3158274/what-would-be-a-regex-for-valid-xml-names
+    private val XML10_START_TAG_PATTERN = Pattern.compile("^[^" + "_" +
+            "A-Z" + "a-z" + "\u00C0-\u00D6" + "\u00F8-\u02FF" +
+            "\u200C-\u200D" + "\u2070-\u218F" + "\u2C00-\u2FEF" +
+            "\u3001-\uD7FF" + "\uF900-\uFDCF" + "\uFDF0-\uFFFD" +
+            "\ud800\udc00-\udbff\udfff" + "]+")
+    private val XML10_TAG_PATTERN = Pattern.compile("[^" + "\\-._" +
+            "0-9" + "\u00B7" + "\u0300-\u036F" + "\u203F-\u2040" +
+            "A-Z" + "a-z" + "\u00C0-\u00D6" + "\u00F8-\u02FF" +
+            "\u200C-\u200D" + "\u2070-\u218F" + "\u2C00-\u2FEF" +
+            "\u3001-\uD7FF" + "\uF900-\uFDCF" + "\uFDF0-\uFFFD" +
+            "\ud800\udc00-\udbff\udfff" + "]")
+
+    fun toNodeName(str: String): String {
+        val nodeName = XML10_START_TAG_PATTERN
+                .matcher(str)
+                .replaceAll("")
+        return XML10_TAG_PATTERN
+                .matcher(nodeName)
+                .replaceAll("_")
+    }
+
+    fun toSafeString(source: Any?, replacement: String): String? {
+        return if (source == null)
+            null
+        else
+            XML10_PATTERN
+                    .matcher(source.toString())
+                    .replaceAll(replacement)
+    }
+}

package/espresso-server/app/src/androidTest/java/io/appium/espressoserver/lib/helpers/extensions/Semaphore.kt

@@ -0,0 +1,22 @@
+package io.appium.espressoserver.lib.helpers.extensions
+
+import java.util.concurrent.Semaphore
+
+fun <R> Semaphore.withPermit(block: () -> R): R {
+    this.acquire()
+    try {
+        return block()
+    } finally {
+        this.release()
+    }
+}
+
+fun <R> Semaphore.withPermit(block: () -> R, finalBlock: () -> Unit): R {
+    this.acquire()
+    try {
+        return block()
+    } finally {
+        finalBlock()
+        this.release()
+    }
+}