chore: Describe how to precompile the server into the AUT (#1043)

Author: mykola-mokhnach

.eslintrc.json

@@ -6,6 +6,3 @@ updates:
     interval: daily
     time: "11:00"
   open-pull-requests-limit: 10
-  commit-message:
-    prefix: "chore"
-    include: "scope"

.github/dependabot.yml

@@ -37,6 +37,17 @@ On top of standard Appium requirements Espresso driver also expects the followin
 - Both the server package and the application under test must be signed with the same digital signature. Appium does sign them automatically upon session creation, so this could only be an issue if one wants to test an application, which is already installed on the device (using `noReset=true` capability).
 - The package under test must not have mangled class names (e.g. [Proguard](https://developer.android.com/studio/build/shrink-code) must not be enabled for it)
 
+
+## Consuming Espresso Server as Library
+
+If you have access to the source code of the application under test then it is
+possible to integrate Espresso server into your application and make it to a library.
+This approach allows to simplify the dependency conflicts resolution
+as well as to optimize the session startup performance.
+Read the corresponding [article](./docs/as-library.md) from the driver
+documentation for more details.
+
+
 ### Doctor
 
 Since driver version 2.31.0 you can automate the validation for the most of the above
@@ -1773,14 +1784,14 @@ Appium allows to do this on per-process (multiple server processes running on di
 or per-request basis (single server process managing multiple sessions, more preferable, uses less resources and ensures better control over running sessions). Check [Parallel Android Tests](docs/parallel-tests.md) article for
 more details.
 
-> **Note**
+> [!NOTE]
 > If you are _not_ going to run your tests in parallel then consider enabling the `--session-override` Appium server argument. It forces the server to close all pending sessions before a new one could be opened,
 > which allows you to avoid possible issues with such sessions silently running/expiring in the background.
 
-
 ## Troubleshooting
 
-* If you observe Espresso server crash on startup and various exceptions about missing class/method in the logcat output then consider updating [appium:espressoBuildConfig](#espresso-build-config) capability with module versions that match your application under test. This might require some experimentation, as different apps have different module requirements. Check, for example, [issue #812](https://github.com/appium/appium-espresso-driver/issues/812)
+* If you observe Espresso server crash on startup and various exceptions about missing class/method in the logcat output then consider updating [appium:espressoBuildConfig](#espresso-build-config) capability with module versions that match your application under test. This might require some experimentation, as different apps have different module requirements. Check, for example, [issue #812](https://github.com/appium/appium-espresso-driver/issues/812). Another solution might be
+to [integrate](#consuming-espresso-server-as-library) Espresso Server with the application under test in form of a library.
 * If you experince issues with application activities being not found or not starting then consider checking [How To Troubleshoot Activities Startup](docs/activity-startup.md) article.
 * Espresso requires the debug APK and app-under-test APK (AUT) to have the same signature. It automatically signs the AUT with the `io.appium.espressoserver.test` signature. This may be problematic if you're using an outdated Android SDK tools and/or an outdated Java version.
 * If there are problems starting a session, set the capability `forceEspressoRebuild` to `true` and retry. This will force rebuilding of Espresso Server. If the following session startup is successfull, set it back to `false`, so the session startup performance is back to normal.

README.md

@@ -0,0 +1,81 @@
+## Consuming Espresso Server as Library
+
+After driver version 3.0.0 it is possible to consume Espresso server as a library,
+apply dependency constraints to align dependency versions,
+and embed it either as androidTest component of the app
+or as a standalone test module under the same
+Gradle project. The library only has to expose a single method for starting a
+server and a TestRule for Compose support.
+This way, the Espresso server APK could be built with the correct versions of AGP,
+Kotlin and dependencies automatically.
+If the app is obfuscated, we could also use [slackhq/keeper](https://github.com/slackhq/keeper)
+to infer the obfuscation rules.
+
+### Building The App Under Test (AUT)
+
+Standalone test module:
+
+```groovy
+plugins {
+    id "com.android.test"
+}
+
+android {
+    namespace = "com.my.espresso.server"
+
+    defaultConfig {
+        testApplicationId = "io.appium.espressoserver.test"
+        minSdk = 21
+        targetSdk = 34
+    }
+
+    targetProjectPath = ":app"
+}
+
+dependencies {
+    implementation "androidx.test:runner:1.6.0"
+    implementation "io.appium.espressoserver:library:<latest_driver_version>"
+}
+```
+
+The test that should reside on the consumer side:
+
+```kotlin
+package com.my.espresso.server
+
+import android.annotation.SuppressLint
+import androidx.test.filters.LargeTest
+import io.appium.espressoserver.lib.http.Server
+import org.junit.Rule
+import org.junit.Test
+
+@LargeTest
+class EspressoServerRunnerTest {
+    @get:Rule
+    val server = Server()
+
+    @Test
+    fun startEspressoServer() {
+        server.run()
+    }
+}
+```
+
+Build both the app and Espresso server:
+
+```bash
+./gradlew :app:assembleDebug :espresso_server:assembleDebug
+```
+
+### Running Appium Tests
+
+As soon as the application containing Espresso server is built it might be used
+to run tests with appium-espresso-driver. The only requirements to run a test are
+- The application build according to the above tutorial is already installed on the device
+- The precompiled Espresso Server module version satisfies the driver version:
+  - At least major versions should match
+  - The driver version must not be older than the server version
+
+Set the [skipServerInstallation](../README.md#driverserver) to
+`true` in your test session capabilities to provide the Espresso driver
+with the hint that Espresso server is already listening on the device under test.