appium-mcp 0.0.1 → 1.1.4

package/src/resources/submodules/appium-xcuitest-driver/docs/guides/wda-custom-server.md

@@ -0,0 +1,283 @@
+---
+title: Manage WebDriverAgent by Yourself
+---
+
+The XCUITest driver uses [WebDriverAgent](https://github.com/appium/WebDriverAgent) (WDA) as the
+automation backend. This backend is based on Apple's XCTest framework and shares all the known
+problems that are present in XCTest. For some of them we have workarounds, but there are some that
+are hardly possible to workaround ([here is one example](https://github.com/facebookarchive/WebDriverAgent/issues/507)).
+The approach described in this article enables you to have full control over how WDA is built,
+managed, and run on the device. This way you may fine-tune your automated tests in a CI environment
+and make them more stable inlong-running perspective.
+
+!!! note
+
+    * The steps below are not necessary if default Appium capabilities are used. The server will do
+      everything for you, however, you will not have so much control over WDA.
+    * It is mandatory to have SSH or physical access to the machine to which the device under test
+      is connected.
+
+
+### WDA Setup
+
+In order to setup and launch WDA, please check the provided steps in the
+[Run Preinstalled WDA](./run-preinstalled-wda.md#using-xcode) documentation.
+
+### WDA Startup via Code
+
+WebDriverAgent application acts as a REST server, which proxies external API requests to native
+XCTest calls for your application under test. The server address will be `localhost` if you run your
+tests on a simulator, or the actual phone IP address in case of real device. Appium uses
+[`appium-ios-device`](https://github.com/appium/appium-ios-device) to route network requests to a
+real device from `localhost` via USB, which means one can use this tool to unify the WDA network
+addresses for a simulator and real device.
+
+You can use `appium-ios-device` to connect to a remote device by requiring the module from your
+JavaScript code. Alternatively, you can use [`iproxy`](https://github.com/libimobiledevice/libusbmuxd#iproxy),
+[`go-ios`](https://github.com/danielpaulus/go-ios) or [`tidevice`](https://github.com/alibaba/taobao-iphone-device)
+to handle the WDA process outside Appium, by installing and launching the WDA package. For instance,
+`iproxy` can be installed using `npm`: `npm install -g iproxy`.
+
+This helper class written in Java illustrates the main implementation details with `iproxy`:
+
+```java
+public class WDAServer {
+    private static final Logger log = ZLogger.getLog(WDAServer.class.getSimpleName());
+
+    private static final int MAX_REAL_DEVICE_RESTART_RETRIES = 1;
+    private static final Timedelta REAL_DEVICE_RUNNING_TIMEOUT = Timedelta.ofMinutes(4);
+    private static final Timedelta RESTART_TIMEOUT = Timedelta.ofMinutes(1);
+
+    // These settings are needed to properly sign WDA for real device tests
+    // See https://github.com/appium/appium-xcuitest-driver for more details
+    private static final File KEYCHAIN = new File(String.format("%s/%s",
+            System.getProperty("user.home"), "/Library/Keychains/MyKeychain.keychain"));
+    private static final String KEYCHAIN_PASSWORD = "******";
+
+    private static final File IPROXY_EXECUTABLE = new File("/usr/local/bin/iproxy");
+    private static final File XCODEBUILD_EXECUTABLE = new File("/usr/bin/xcodebuild");
+    private static final File WDA_PROJECT =
+            new File("~/.appium/node_modules/appium-xcuitest-driver/node_modules/appium-webdriveragent" +
+                    "/WebDriverAgent.xcodeproj");
+    private static final String WDA_SCHEME = "WebDriverAgentRunner";
+    private static final String WDA_CONFIGURATION = "Debug";
+    private static final File XCODEBUILD_LOG = new File("/usr/local/var/log/appium/build.log");
+    private static final File IPROXY_LOG = new File("/usr/local/var/log/appium/iproxy.log");
+
+    private static final int PORT = 8100;
+    public static final String SERVER_URL = String.format("http://127.0.0.1:%d", PORT);
+
+    private static final String[] IPROXY_CMDLINE = new String[]{
+            IPROXY_EXECUTABLE.getAbsolutePath(),
+            Integer.toString(PORT),
+            Integer.toString(PORT),
+            String.format("> %s 2>&1 &", IPROXY_LOG.getAbsolutePath())
+    };
+
+    private static WDAServer instance = null;
+    private final boolean isRealDevice;
+    private final String deviceId;
+    private final String platformVersion;
+    private int failedRestartRetriesCount = 0;
+
+    private WDAServer() {
+        try {
+            this.isRealDevice = !getIsSimulatorFromConfig(getClass());
+            final String udid;
+            if (isRealDevice) {
+                udid = IOSRealDeviceHelpers.getUDID();
+            } else {
+                udid = IOSSimulatorHelpers.getId();
+            }
+            this.deviceId = udid;
+            this.platformVersion = getPlatformVersionFromConfig(getClass());
+        } catch (Exception e) {
+            throw new RuntimeException(e);
+        }
+        ensureToolsExistence();
+        ensureParentDirExistence();
+    }
+
+    public synchronized static WDAServer getInstance() {
+        if (instance == null) {
+            instance = new WDAServer();
+        }
+        return instance;
+    }
+
+    private boolean waitUntilIsRunning(Timedelta timeout) throws Exception {
+        final URL status = new URL(SERVER_URL + "/status");
+        try {
+            if (timeout.asSeconds() > 5) {
+                log.debug(String.format("Waiting max %s until WDA server starts responding...", timeout));
+            }
+            new UrlChecker().waitUntilAvailable(timeout.asMillis(), TimeUnit.MILLISECONDS, status);
+            return true;
+        } catch (UrlChecker.TimeoutException e) {
+            return false;
+        }
+    }
+
+    private static void ensureParentDirExistence() {
+        if (!XCODEBUILD_LOG.getParentFile().exists()) {
+            if (!XCODEBUILD_LOG.getParentFile().mkdirs()) {
+                throw new IllegalStateException(String.format(
+                        "The script has failed to create '%s' folder for Appium logs. " +
+                                "Please make sure your account has correct access permissions on the parent folder(s)",
+                        XCODEBUILD_LOG.getParentFile().getAbsolutePath()));
+            }
+        }
+    }
+
+    private void ensureToolsExistence() {
+        if (isRealDevice && !IPROXY_EXECUTABLE.exists()) {
+            throw new IllegalStateException(String.format("%s tool is expected to be installed (`npm install -g iproxy`)",
+                    IPROXY_EXECUTABLE.getAbsolutePath()));
+        }
+        if (!XCODEBUILD_EXECUTABLE.exists()) {
+            throw new IllegalStateException(String.format("xcodebuild tool is not detected on the current system at %s",
+                    XCODEBUILD_EXECUTABLE.getAbsolutePath()));
+        }
+        if (!WDA_PROJECT.exists()) {
+            throw new IllegalStateException(String.format("WDA project is expected to exist at %s",
+                    WDA_PROJECT.getAbsolutePath()));
+        }
+    }
+
+    private List<String> generateXcodebuildCmdline() {
+        final List<String> result = new ArrayList<>();
+        result.add(XCODEBUILD_EXECUTABLE.getAbsolutePath());
+        result.add("clean build-for-testing test-without-building");
+        result.add(String.format("-project %s", WDA_PROJECT.getAbsolutePath()));
+        result.add(String.format("-scheme %s", WDA_SCHEME));
+        result.add(String.format("-destination id=%s", deviceId));
+        result.add(String.format("-configuration %s", WDA_CONFIGURATION));
+        result.add(String.format("IPHONEOS_DEPLOYMENT_TARGET=%s", platformVersion));
+        result.add(String.format("> %s 2>&1 &", XCODEBUILD_LOG.getAbsolutePath()));
+        return result;
+    }
+
+    private static List<String> generateKeychainUnlockCmdlines() throws Exception {
+        final List<String> result = new ArrayList<>();
+        result.add(String.format("/usr/bin/security -v list-keychains -s %s", KEYCHAIN.getAbsolutePath()));
+        result.add(String.format("/usr/bin/security -v unlock-keychain -p %s %s",
+                KEYCHAIN_PASSWORD, KEYCHAIN.getAbsolutePath()));
+        result.add(String.format("/usr/bin/security set-keychain-settings -t 3600 %s", KEYCHAIN.getAbsolutePath()));
+        return result;
+    }
+
+    public synchronized void restart() throws Exception {
+        if (isRealDevice && failedRestartRetriesCount >= MAX_REAL_DEVICE_RESTART_RETRIES) {
+            throw new IllegalStateException(String.format(
+                    "WDA server cannot start on the connected device with udid %s after %s retries. " +
+                            "Reboot the device manually and try again", deviceId, MAX_REAL_DEVICE_RESTART_RETRIES));
+        }
+
+        final String hostname = InetAddress.getLocalHost().getHostName();
+        log.info(String.format("Trying to (re)start WDA server on %s:%s...", hostname, PORT));
+        UnixProcessHelpers.killProcessesGracefully(IPROXY_EXECUTABLE.getName(), XCODEBUILD_EXECUTABLE.getName());
+
+        final File scriptFile = File.createTempFile("script", ".sh");
+        try {
+            final List<String> scriptContent = new ArrayList<>();
+            scriptContent.add("#!/bin/bash");
+            if (isRealDevice && isRunningInJenkinsNetwork()) {
+                scriptContent.add(String.join("\n", generateKeychainUnlockCmdlines()));
+            }
+            if (isRealDevice) {
+                scriptContent.add(String.join(" ", IPROXY_CMDLINE));
+            }
+            final String wdaBuildCmdline = String.join(" ", generateXcodebuildCmdline());
+            log.debug(String.format("Building WDA with command line:\n%s\n", wdaBuildCmdline));
+            scriptContent.add(wdaBuildCmdline);
+            try (Writer output = new BufferedWriter(new FileWriter(scriptFile))) {
+                output.write(String.join("\n", scriptContent));
+            }
+            new ProcessBuilder("/bin/chmod", "u+x", scriptFile.getCanonicalPath())
+                    .redirectErrorStream(true).start().waitFor(5, TimeUnit.SECONDS);
+            final ProcessBuilder pb = new ProcessBuilder("/bin/bash", scriptFile.getCanonicalPath());
+            final Map<String, String> env = pb.environment();
+            // This is needed for Jenkins
+            env.put("BUILD_ID", "dontKillMe");
+            // This line is important. If USE_PORT environment variable is not set then WDA
+            // takes port number zero by default and won't accept any incoming requests
+            env.put("USE_PORT", Integer.toString(PORT));
+            log.info(String.format("Waiting max %s for WDA to be (re)started on %s:%s...", RESTART_TIMEOUT.toString(),
+                    hostname, PORT));
+            final Timedelta started = Timedelta.now();
+            pb.redirectErrorStream(true).start().waitFor(RESTART_TIMEOUT.asMillis(), TimeUnit.MILLISECONDS);
+            if (!waitUntilIsRunning(RESTART_TIMEOUT)) {
+                ++failedRestartRetriesCount;
+                throw new IllegalStateException(
+                        String.format("WDA server has failed to start after %s timeout on server '%s'.\n"
+                                        + "Please make sure that iDevice is properly connected and you can build "
+                                        + "WDA manually from XCode.\n"
+                                        + "Xcodebuild logs:\n\n%s\n\n\niproxy logs:\n\n%s\n\n\n",
+                                RESTART_TIMEOUT, hostname,
+                                getLog(XCODEBUILD_LOG).orElse("EMPTY"), getLog(IPROXY_LOG).orElse("EMPTY"))
+                );
+            }
+
+            log.info(String.format("WDA server has been successfully (re)started after %s " +
+                    "and now is listening on %s:%s", Timedelta.now().diff(started).toString(), hostname, PORT));
+        } finally {
+            scriptFile.delete();
+        }
+    }
+
+    public boolean isRunning() throws Exception {
+        if (!isProcessRunning(XCODEBUILD_EXECUTABLE.getName())
+                || (isRealDevice && !isProcessRunning(IPROXY_EXECUTABLE.getName()))) {
+            return false;
+        }
+        return waitUntilIsRunning(isRealDevice ? REAL_DEVICE_RUNNING_TIMEOUT : Timedelta.ofSeconds(3));
+    }
+
+    public Optional<String> getLog(File logFile) {
+        if (logFile.exists()) {
+            try {
+                return Optional.of(new String(Files.readAllBytes(logFile.toPath()), Charset.forName("UTF-8")));
+            } catch (IOException e) {
+                e.printStackTrace();
+            }
+        }
+        return Optional.empty();
+    }
+}
+```
+
+The following piece of code should then be called before starting the XCUITest driver:
+
+```java
+if (!WDAServer.getInstance().isRunning()) {
+    WDAServer.getInstance().restart();
+}
+```
+
+It is important to set the `appium:webDriverAgentUrl` capability for the driver to let it know
+that WDA is ready for use:
+
+```java
+capabilities.setCapability("webDriverAgentUrl", WDAServer.SERVER_URL);
+```
+
+### Important Notes
+
+* The process does not have direct access to keychain if it is executed by a continuous integration
+  agent, so the keychain must be prepared before compiling WDA for real device, otherwise
+  codesigning will fail. Check the [CI Setup](./ci-setup.md) documentation for details.
+* The `xcodebuild` and `iproxy` processes are killed before restart to make sure compilation
+  succeeds, in case the processes are frozen
+* A dedicated `bash` script is used to detach the `iproxy`/`xcodebuild` processes, so they can
+  continue running in background even after the actual code execution is finished. This is extremely
+  important if multiple tests/suites are executed on the same machine/node in automation lab, which
+  requires minimum human interaction
+* The value of the `BUILD_ID` environment variable is changed to avoid the CI agent killing the
+  background process after the job is finished
+* The `isRunning` check is done by verifying the actual network endpoint
+* The output of daemonized processes is logged, so it is possible to track errors and unexpected
+  failures. The content of the log files is automatically added to the actual error message if the
+  server fails to (re)start.
+* Real device id can be parsed from `system_profiler SPUSBDataType` output
+* Simulator id can be parsed from `xcrun simctl list` output
+* The `UrlChecker` class is imported from the `org.openqa.selenium.net` package

package/src/resources/submodules/appium-xcuitest-driver/docs/guides/wda-slowness.md

@@ -0,0 +1,231 @@
+---
+title: Diagnosing WebDriverAgent Slowness
+---
+
+The XCUITest driver is based on Apple's [XCTest](https://developer.apple.com/documentation/xctest)
+test automation framework and thus inherits most (if not all) properties and features this framework
+provides. The purpose of this article is to help with optimization of automation scenarios that
+don't perform well and/or to explain possible causes of such behavior.
+
+## "Slowness" could be different
+
+First, it is important to figure out what exactly is slow.
+The Appium ecosystem is complicated and
+consists of multiple layers, where each layer could influence the overall duration.
+For example, when an API call is invoked from a client script, it must go through the following stages:
+
+Your automation script (Java, Python, C#, etc; runs on your machine)
+--> Appium Client Lib (Java, Python, C#, etc; runs on your machine)
+--> Appium Server (Node.js HTTP server; runs on your machine or a remote one)
+--> XCUITest Driver and/or Plugin (Node.js HTTP handler; runs on your machine or a remote one)
+--> WDA Server (ObjectiveC HTTP Server; runs on the remote mobile device)
+
+The example above is the simplest flow. If you run your scripts using cloud providers
+infrastructure then the amount of intermediate components in this chain may be much greater.
+Like it was mentioned above, it is very important to know on which stage(s)
+(or between them) the bottleneck is observed.
+
+This particular article focuses only on the last stage: the WDA Server one.
+
+## WebDriverAgent (WDA) Server
+
+WDA source code is located in the separate [repository](https://github.com/appium/WebDriverAgent/tree/master).
+The content of this repository is published as [appium-webdriveragent](https://www.npmjs.com/package/appium-webdriveragent)
+NPM package and contains several helper Node.js modules along with the WDA source code itself.
+This source code is compiled into an .xctrunner bundle, which is a special application type
+that contains tests (also it has some higher privileges in comparison to vanilla apps).
+WebDriverAgent project itself consists of three main parts:
+
+- Vendor Libs
+- WebDriverAgentLib
+- WebDriverAgentRunner
+
+Vendor libs, like RoutingHTTPServer, ensure the support for low-level HTTP- and TCP-server APIs.
+WebDriverAgentLib defines handlers for [W3C WebDriver](https://www.w3.org/TR/webdriver/) endpoints
+and implements all the heavy-lifting procedures related to Apple's XCTest communication
+and some more custom stuff specific for the XCUITest driver.
+WebDriverAgentRunner is actually one long test, whose main purpose
+is to run the HTTP server implemented by the WebDriverAgentLib.
+
+Important conclusions from the above information:
+
+- WDA is an HTTP server, which executes API commands by invoking HTTP response handlers
+- WDA uses Apple's XCTest APIs with various custom additions
+
+## How to confirm my script's bottleneck is WDA
+
+Check the server logs in order to verify how long it takes for the XCUITest driver to receive a
+response from WDA. The log line that is written before an HTTP request is proxied to WDA looks
+like `Proxying [X] to [Y]`. Also consider enabling server timestamps by providing the
+`--log-timestamp` command line parameter. If you observe timestamps between the above log line and the
+next one differ too much and the difference is an anomaly (e.g. the same step is (much) faster
+for other apps/environments/parameter combinations) then it might serve as a confirmation of a
+suspicious slowness.
+
+## Patterns lookup
+
+After the slowness is confirmed it is important to determine behavior patterns, e.g. under which
+circumstances does it happen, if it is always reproducible, etc. This article only targets specific
+patterns that the author knows of or dealt with. If your pattern is not present here then try to
+look for possible occurrences in existing [issues](https://github.com/appium/appium/issues),
+[Appium forum](https://discuss.appium.io) or just search the internet.
+
+## Pattern: Application startup is slow
+
+### Symptoms
+
+You observe timeouts or unusual slowness (in comparison to manual execution performance)
+of the application startup on session init (if it also includes app startup)
+or mid-session app startup.
+
+### Causes
+
+When XCTest starts an app it ensures the accessibility layer of it is ready for interactions.
+To check that the framework verifies the application is idling (e.g. does not perform any actions
+on the main thread) as well as all animations have been finished. If this check times out
+an exception is thrown or WDA may try to continue without any guarantees the app could be
+interacted with (a.k.a. best effort strategy).
+
+### Solutions
+
+I was observing applications that were constantly running something on the main thread in an endless loop.
+Most likely such apps are not automatable at all or hardly automatable without fixing the app
+source code itself.
+You may still try to tune the following capabilities and settings to influence the above timeout:
+
+- [appium:waitForIdleTimeout](../reference/capabilities.md)
+- [waitForIdleTimeout](../reference/settings.md)
+- [animationCoolOffTimeout](../reference/settings.md)
+
+## Pattern: Element location with XPath is slow
+
+### Symptoms
+
+You observe timeouts or unusual slowness (in comparison to other location strategies)
+of XPath locators.
+
+### Causes
+
+The [XPath](../reference/locator-strategies.md) location strategy
+is not natively supported by XCTest. It's a custom addition
+which is only available in WDA. Such locators have more features than others, but the price
+for it is the observed slowness as we cannot rely on native XCTest location APIs
+while looking for elements using XPath.
+In order to perform XPath lookup WDA needs to take a snapshot of the whole accessibility
+hierarchy with all element attributes resolved, which is a time-expensive operation.
+Location slowness might be observed if:
+- The current app hierarchy is too large (e.g. has hundreds of elements). This is a known
+  XCTest limitation.
+- The app is not idling/has active animations
+- It takes too long to determine each element's `visible` or `accessible` attributes, which are custom
+  ones and are not present in the original XCTest implementation
+
+### Solutions
+
+Depending on the actual cause there might be different applicable solutions. In general, the common
+advice would be to avoid XPath locators where possible and use locators that are natively
+supported by XCTest (like predicates or ids) and have better speed ranking.
+If the usage of an XPath locators is a single available option then you may try to apply the following
+suggestions:
+- Reduce the size of the app hierarchy using the [snapshotMaxDepth setting](../reference/settings.md).
+  This might not help if the destination element is deeply nested -
+  it won't be found if the value of this setting is lower than its nesting level.
+- Exclude the `visible` and/or `accessible` attributes from your query. These are
+  custom attributes exclusive to WDA and their calculation is expensive in comparison
+  to other native attributes.
+- Reduce various timeouts similarly to how it's advised in the
+  [Application startup is slow](#pattern-application-startup-is-slow) pattern
+- Fix the source code of the application under test to reduce the amount of accessible elements
+  on a single screen
+- Fix the source code of the application under test to avoid running long operations
+  or animations on the main thread
+
+## Pattern: Element location with non-XPath is slow
+
+### Symptoms
+
+You observe timeouts or unusual slowness with various non-XPath locators.
+
+### Causes
+
+Location slowness might be observed if:
+- The current app hierarchy is too large (e.g. has hundreds of elements). This is a known
+  XCTest limitation.
+- The app is not idling/has active animations
+- It takes too long to determine each element's `visible` or `accessible` attributes, which are custom
+  ones and are not present in the original XCTest implementation (only applicable to predicate and class chain locators)
+
+### Solutions
+
+- Reduce the size of the app hierarchy using the [snapshotMaxDepth setting](../reference/settings.md).
+  This might not help if the destination element is deeply nested -
+  it won't be found if the value of this setting is lower than its nesting level.
+- Exclude the `visible` and/or `accessible` attributes from your query
+  (only applicable to predicate and class chain locators). These are
+  custom attributes exclusive to WDA and their calculation is expensive in comparison
+  to other native attributes.
+- Reduce various timeouts similarly to how it's advised in the
+  [Application startup is slow](#pattern-application-startup-is-slow) pattern
+- Fix the source code of the application under test to reduce the amount of accessible elements
+  on a single screen
+- Fix the source code of the application under test to avoid running long operations
+  or animations on the main thread
+
+## Pattern: Various element interactions are slow
+
+### Symptoms
+
+You observe timeouts or unusual slowness while clicking elements or performing other
+actions on them.
+
+### Causes
+
+- The current app hierarchy is too large (e.g. has hundreds of elements). This is a known
+  XCTest limitation.
+- The app is not idling/has active animations
+
+### Solutions
+
+- Reduce various timeouts similarly to how it's advised in the
+  [Application startup is slow](#pattern-application-startup-is-slow) pattern
+- Fix the source code of the application under test to reduce the amount of accessible elements
+  on a single screen
+- Fix the source code of the application under test to avoid running long operations
+  or animations on the main thread
+
+## Pattern: Page source retrieval slow
+
+### Symptoms
+
+You observe timeouts or unusual slowness while retrieving the page of the app.
+
+### Causes
+
+In order to retrieve the page source WDA needs to take a snapshot of the whole accessibility
+hierarchy with all element attributes resolved, which is a time-expensive operation.
+Page source retrieval slowness might be observed if:
+- The current app hierarchy is too large (e.g. has hundreds of elements). This is a known
+  XCTest limitation.
+- The app is not idling/has active animations
+- It takes too long to determine each element's `visible` or `accessible` attributes, which are custom
+  ones and are not present in the original XCTest implementation
+
+### Solutions
+
+- Reduce the size of the app hierarchy using the [snapshotMaxDepth setting](../reference/settings.md).
+  Note that you won't see nested elements in the source tree whose nesting level is greater than
+  the given size.
+- Retrieve the page source without "expensive" attributes using the
+  [mobile: source](../reference/execute-methods.md#mobile-source) method with
+  the appropriate `excludedAttributes` argument value or add such attribute names into
+  the [pageSourceExcludedAttributes setting](../reference/settings.md).
+- Retrieve the native XCTest page source using the
+  [mobile: source](../reference/execute-methods.md#mobile-source) method with
+  the `format=description` argument value. The returned page source is a poorly-formatted text,
+  although its retrieval should be fast (at least not slower than XCTest does that).
+- Reduce various timeouts similarly to how it's advised in the
+  [Application startup is slow](#pattern-application-startup-is-slow) pattern
+- Fix the source code of the application under test to reduce the amount of accessible elements
+  on a single screen
+- Fix the source code of the application under test to avoid running long operations
+  or animations on the main thread

package/src/resources/submodules/appium-xcuitest-driver/docs/index.md

@@ -0,0 +1,36 @@
+---
+hide:
+  - navigation
+  - toc
+
+title: Welcome
+---
+<style>
+  .md-typeset h1 {
+    display: none;
+  }
+</style>
+
+<div style="text-align: center">
+  <img src="assets/images/appium-plus-xctest.png" style="max-width: 500px;" />
+</div>
+
+Welcome to the Appium XCUITest Driver documentation! The XCUITest driver is a test automation
+framework for iOS, iPadOS and tvOS devices, enabling automated black-box testing of native, hybrid
+and WebKit web apps, on both emulators and real devices. 
+
+The XCUITest driver is part of the Appium test automation tool. For information on Appium itself,
+please visit [the Appium documentation](https://appium.io).
+
+## Explore the Documentation
+
+<div class="grid cards" markdown>
+
+-   Check out the [__Overview__](./overview.md) to learn how the driver works
+-   Go through the [__Installation__](./installation/index.md) steps to get set up
+-   Follow the [__Device Preparation__](./preparation/index.md) instructions to configure your test device
+-   Browse the [__Reference__](./reference/scripts.md) documentation for everything exposed by the driver
+-   Read the different [__Guides__](./guides/parallel-tests.md) for a variety of instructions, tips and tricks
+-   For contributions to the driver, refer to the [__Contributing__](./contributing.md) page
+
+</div>