appium-mcp 0.0.1 → 1.1.5

package/src/resources/submodules/appium/packages/appium/docs/en/guides/tls.md

@@ -0,0 +1,42 @@
+---
+hide:
+  - toc
+
+title: SSL/TLS/SPDY Support
+---
+
+Appium 2.2 introduces the option to start the Appium server with SSL/TLS support. 
+
+## Command Line Arguments
+In order to enable secure connections to the server, you need to provide the following command
+line arguments:
+
+```bash
+appium server --ssl-cert-path=/path/to/cert.pem --ssl-key-path=/path/to/key.pem
+```
+
+Both arguments must be provided and should contain paths to a valid
+[X509 PEM](https://www.ssl.com/guide/pem-der-crt-and-cer-x-509-encodings-and-conversions/)
+certificate and its corresponding private key.
+
+After the server is started use the `https` protocol and a client supporting SSL/TLS or
+[SPDY](https://en.wikipedia.org/wiki/SPDY) to communicate to it.
+
+### Supported Features
+
+Once a secure server socket is established it supports the following protocols:
+`['h2', 'spdy/3.1', 'spdy/3', 'spdy/2', 'http/1.1', 'http/1.0']`. See
+[the SPDY node module documentation](https://www.npmjs.com/package/spdy) to get more details about
+its features. All insecure client connections will be rejected by the server.
+
+### Self-Signed Certificates
+
+Use the following command in order to generate a self-signed certificate/key pair:
+
+```bash
+openssl req -nodes -new -x509 -keyout key.pem -out cert.pem -subj "/C=US/ST=State/L=City/O=company/OU=Com/CN=www.testserver.local"
+```
+
+Feel free to change the value of `-subj` in the command above with your matching details. The server
+should work just fine with a self-signed certificate, although you need to take care about a proper
+client setup, e.g. make sure it does not reject unauthorized certificates.

package/src/resources/submodules/appium/packages/appium/docs/en/index.md

@@ -0,0 +1,59 @@
+---
+hide:
+  - navigation
+  - toc
+
+title: Welcome
+---
+<style>
+  .md-typeset h1,
+  .appium-sponsor-thanks {
+    display: none;
+  }
+</style>
+
+<div style="text-align: center">
+  <img src="assets/images/appium-logo-horiz.png" style="max-width: 400px;" />
+</div>
+
+Welcome to the Appium documentation! Appium is an open-source project and ecosystem of related
+software, designed to facilitate UI automation of many app platforms, including mobile (iOS,
+Android, Tizen), browser (Chrome, Firefox, Safari), desktop (macOS, Windows), TV (Roku, tvOS,
+Android TV, Samsung), and more!
+
+
+<div style="text-align: center; margin-top: 2rem; font-style: italic;">
+  Appium is extremely grateful for the support of its key partners! (Learn more about our
+  sponsorship program and contributor compensation scheme <a
+  href="https://github.com/appium/appium/blob/master/GOVERNANCE.md#sponsorship">here</a>)
+  <div class="homepageSponsors">
+    <div class="homepageSponsor">
+      <a href="https://www.browserstack.com/browserstack-appium?utm_campaigncode=701OW00000AoUTQYA3&utm_medium=partnered&utm_source=appium">
+        <img src="assets/images/sponsor-logo-browserstack-dark.png#only-dark" style="width: 220px;" />
+        <img src="assets/images/sponsor-logo-browserstack-light.png#only-light" style="width: 220px;" />
+      </a>
+    </div>
+    <div class="homepageSponsor">
+      <a href="https://lambdatest.com/?utm_source=appium.io&utm_medium=organic&utm_campaign=june_25&utm_term=sk&utm_content=webpage">
+        <img src="assets/images/sponsor-logo-lambdatest-dark.png#only-dark" style="width: 220px;" />
+        <img src="assets/images/sponsor-logo-lambdatest-light.png#only-light" style="width: 220px;" />
+      </a>
+    </div>
+  </div>
+</div>
+
+## Explore the Documentation
+
+<div class="grid cards" markdown>
+
+-   Check out the [__Introduction__](./intro/index.md) to make sure you understand the key concepts
+-   Go through the [__Quickstart__](./quickstart/index.md) to get set up and run a basic Android test
+-   Visit the [__Ecosystem__](./ecosystem/index.md) page for a list of drivers, clients and plugins you may want to use
+-   Consult the [__Reference__](./reference/index.md) page for information on the Appium CLI and supported endpoints
+-   Read the different [__Guides__](./guides/migrating-2-to-3.md) for a variety of instructions, tips and tricks
+-   Check out various third-party [__Resources__](./resources/index.md) to explore Appium around the web
+-   For creating your own Appium extensions, see the [__Developer__](./developing/index.md) documentation
+-   For contributions to Appium itself, refer to the [__Contributing__](./contributing/index.md) page
+-   Have a look at the [__Appium Blog__](./blog/index.md) to learn what's new in the project
+
+</div>

package/src/resources/submodules/appium/packages/appium/docs/en/intro/appium.md

@@ -0,0 +1,202 @@
+---
+title: How Does Appium Work?
+---
+
+As mentioned on the main page, Appium is an open-source project and ecosystem of related software,
+designed to facilitate UI automation of many app platforms. With the release of Appium 2, Appium
+has the following primary goals:[^1]
+
+- Make platform-specific automation capabilities available under a cross-platform, standard API
+- Allow easy access to this API from any programming language
+- Provide tools to enable convenient community development of Appium extensions
+
+[^1]:
+    To meet these primary goals, we also work with a set of secondary goals or methodology
+    principles, which we also encourage for Appium extension developers:
+
+    - As far as possible, rely on (and contribute to) open source technology
+    - As far as possible, rely on vendor-provided tools for a given platform
+    - As far as possible, rely on automation tools that allow automation of unmodified apps (prefer
+      not to require the user to build in additional SDKs or software that introduce discrepancies
+      between the test version of the app and the production version)
+    - As far as possible, rely on existing standards instead of creating new ones
+
+So, take any app platform you know about, like iOS or Android. Appium wants for there to be a way
+for developers and testers to write UI automation code for that platform, according to a single,
+unified API. Based on Appium's goals, we have a lot of questions to answer to make it all work:
+
+- Which API should that "single, unified" API be?
+- How do we map that API to automation behaviour for a specific platform?
+- How do we make that API accessible via multiple popular programming languages?
+
+There's another, larger, question lurking in the background here too, given that there are more app
+platforms out there than just iOS and Android:
+
+- How do we enable automation for *all* the platforms?
+
+Exploring Appium's answers to these questions may not be the quickest way to learn what Appium is,
+but it is certainly a good one! So let's dive in.
+
+## Appium's choice of API
+
+Appium is very fortunate to have been preceded by a technology which has been a long-standing
+pioneer in the field of UI automation, namely [Selenium](https://selenium.dev). The goal of the
+Selenium project has been to support UI automation of web browsers, and in this way we can think of
+it as occupying a subset of Appium's goals. Along the way, Selenium (and, after they merged,
+another project called WebDriver) developed a relatively stable API for browser automation.
+
+Over the years, Selenium worked with various web browser vendors and the [W3C](https://w3.org)
+standards group to turn its API into an official web browser standard, called the [WebDriver
+specification](https://w3c.github.io/webdriver/). All the main browsers now
+implement automation capabilities inline with the WebDriver spec, without the Selenium team having
+to maintain any software that performs actual automation; standards for the win!
+
+Appium's initial goals were to develop an automation standard for mobile apps (iOS and Android). We
+could have made up something new, but in the spirit of joining forces and keeping standards, well,
+standard, we decided to adopt the WebDriver spec as Appium's API.[^2] While user interaction on
+websites and in mobile native apps are not entirely identical (with even greater differences once
+we start to consider, for example, TV platforms controlled by simple remotes), the fact is that
+most software UIs are pretty much the same. This means that the WebDriver spec provides automation
+API primitives (finding elements, interacting with elements, loading pages or screens, etc...) that
+more or less map to any platform.
+
+[^2]: Technically, when Appium was first written, we were dealing with something older than the
+  WebDriver spec, called the JSON Wire Protocol. Since then, Appium continued to evolve along with
+  the W3C spec and is fully W3C-compliant.
+
+Of course, Appium wants to support the cases where user interaction *does* differ from web to
+mobile or web to TV, and so Appium also makes use of the built-in *extensibility* of the WebDriver
+spec. The result is that, no matter what platform you want to automate, when you use Appium, you
+will do so using the standard WebDriver spec, with two caveats:
+
+- We might not have any way to support a particular WebDriver API command on a given platform, and
+  so some commands might be unsupported (for example, getting or setting cookies is not possible in
+  the world of native mobile app automation).
+- We might support automation behaviours that go *beyond* what's available in the WebDriver API
+  command list, though any such commands will be valid and spec-compliant extensions to the
+  WebDriver API.
+
+How do you actually *use* the WebDriver API, particularly in the context of Appium? We'll cover
+that in the [section below](#universal-programming-language-access) on how Appium provides
+universal programming language access. All you need to know for now is that the way Appium
+introduces a universal UI automation interface is by implementing the WebDriver protocol.
+
+## Platform automation behaviour
+
+The next question is, how does Appium map this protocol to automation behaviour on a wide range of
+platforms? The trick is that, strictly speaking, Appium doesn't! It leaves this responsibility up
+to a kind of software module called an Appium *driver*. There's a whole [Driver
+Introduction](./drivers.md) which you can read next, so we won't go into huge detail on how they
+work for now.
+
+What's important to understand at the moment is that a driver is kind of like a pluggable module
+for Appium that gives Appium the power to automate a particular platform (or set of platforms,
+depending on the goal of the driver). At the end of the day, a driver's responsibility is to simply
+implement an Appium-internal interface representing the WebDriver protocol. How it implements this
+interface is totally up to the driver, based on its strategy for making automation happen on
+a specific platform. Typically, and with a lot more complexity and difficulty in the details,
+a driver does this by relying on platform-specific automation technologies. For example, Apple
+maintains an iOS automation technology called
+[XCUITest](https://developer.apple.com/documentation/xctest/user_interface_tests). The Appium
+driver that supports iOS app automation is called the [XCUITest
+Driver](https://github.com/appium/appium-xcuitest-driver) because ultimately what it does is
+convert the WebDriver protocol to XCUITest library calls.
+
+One of the reasons that drivers are independent, pluggable modules is that they work completely
+differently from one another. The tools and requirements for building and using drivers for
+different platforms are completely different. And so Appium lets you use just the drivers that you
+need for your automation tasks. Choosing drivers and installing them so that you can use them with
+your Appium instance is so important that Appium has its very own [CLI for managing
+drivers](../reference/cli/extensions.md).
+
+So, to answer our original question, the way that Appium provides access to automation capabilities
+for a given platform is that the Appium team (or anyone else[^3]) writes a *driver* for that
+platform, implementing as much or little of the WebDriver protocol as desired. The driver can then
+be installed by anyone using Appium.
+
+[^3]: You can build and share your own drivers! Check out [Building
+  Drivers](../developing/build-drivers.md) to learn more about how to develop drivers in Node.js
+  that can be used with Appium.
+
+## Universal programming language access
+
+But what does it mean, or look like, to *use* Appium, anyway? Since Appium is ultimately a Node.js
+program, it *could* have looked like importing Appium and its drivers as libraries into your own
+Node.js programs. But that wouldn't meet Appium's goal of providing automation capabilities to
+people using any popular programming language.
+
+Luckily, the fact that Appium rode in on Selenium's coattails meant that we had a solution to this
+problem from day one. You see, the WebDriver specification is actually an HTTP-based protocol,
+meaning it is designed to be used over a network rather than within the memory of a single program.
+
+One of the main benefits of this "client-server" architecture is that it allows the automation
+implementer (the thing doing the automation, in this case the 'server') to be completely distinct
+from the automation runner (the thing defining what automation should be done, in what steps,
+etc..., in this case the 'client'). Basically, all the "hard stuff" (actually figuring out how to
+make automation happen on a given platform) can be handled in one place by the server, and "thin"
+client libraries can be written in any programming language which simply encode HTTP requests to
+the server in language-appropriate way. It's possible, in other words, to bring basic Appium
+/ WebDriver capabilities to a new programming language relatively easily, assuming high-level HTTP
+libraries exist, simply by coding up a basic HTTP client in that language.
+
+There are a couple important takeaways here for you, the Appium user:
+
+- Appium is an *HTTP server*. It must run as a process on some computer for as long as you want to
+  be able to use it for automation. It must be accessible on the network to whichever computer you
+  want to use to run the automation from (whether that is the same machine or one across the
+  world).
+- Unless you want to write raw HTTP calls or use cURL, using Appium for automation involves the use
+  of an [Appium Client](clients.md) in the language of your choice. The goal of each of these
+  clients is to encapsulate the WebDriver protocol so that rather than worrying about the protocol
+  itself, you can work with objects and methods that feel idiomatic for your language.
+- The Appium server and the Appium client do *not* need to be running on the same computer. You
+  simply need to be able to send HTTP requests from the client to the server over some network.
+  This greatly facilitates the use of cloud providers for Appium, since they can host the Appium
+  server and any related drivers and devices, and all you need to do is point your client script to
+  their secure endpoints.
+
+And of course, none of this is about "testing" per se, purely about the use of Appium and its
+client libraries for automation purposes. If you want to do automation for the purpose of
+"testing", you'll likely want to enlist the help of test runners, test frameworks, and the like,
+none of which need be related to Appium; one of the benefits of Appium's "universal accessibility"
+is that it plays well with whatever set of tools you find most beneficial for your situation.
+
+## Appium's huge scope
+
+Appium's vision (automation of everything under a single API) is huge! Certainly, much bigger than
+the team of core maintainers for the open source project. So how does Appium hope to achieve this
+goal? Basically, by empowering the community to develop functionality on top of Appium as
+a *platform*. This is what we call the Appium "ecosystem".
+
+The Appium team does officially maintain a few drivers itself (for example, the XCUITest driver
+that we spoke about earlier). But it cannot hope to have the platform-specific expertise or the
+capacity to maintain drivers for many different platforms. But what we have done, particularly
+beginning with Appium 2, is to provide tools to empower the community to join in our vision:
+
+- Anyone can create a driver simply by creating a Node.js module that conforms to the appropriate
+  conventions and implements any (sub|super)set of the WebDriver protocol. Creating a driver often
+  involves a minimal amount of code because the WebDriver protocol details are abstracted away, and
+  many helper libraries are available---the same libraries that power the Appium team's own
+  drivers.
+- Sharing drivers with others is easy using the Appium driver CLI. There is no central authority.
+  Anyone can share drivers publicly or privately, for free or for sale. Drivers can be open or
+  closed source (though obviously we appreciate open source!).
+
+Appium's vision of being a platform for development extends beyond the support of automation for
+all app platforms. As a popular automation tool, there are many opportunities for integrating
+Appium with all kinds of other tools and services. In addition, there are many feature ideas for
+Appium, either as a core server or in its incarnation across various drivers, which the core team
+will never have time to build. And so, with Appium 2, Appium has released a plugin system that
+enables anyone to build and share modules that change how Appium works!
+
+In the same way that drivers are easily shareable and consumable via the Appium driver CLI, plugins
+can be published and consumed via a parallel [Plugin CLI](../reference/cli/extensions.md). Plugins
+can do all sorts of things, for example adding the ability for Appium to find and interact with
+screen regions based on a template image (as in the [`images`
+plugin](https://github.com/appium/appium/tree/master/packages/images-plugin)). There are very few
+limitations on what you can do with plugins, so you might also be interested in learning how to
+[Build Plugins](../developing/build-plugins.md) in Node.js that can be used with Appium.
+
+So that's Appium: an extensible, universal interface for the UI automation of potentially
+everything! Read on into some of the specific intro docs for more details, or check out the various
+guides to dive into some more general concepts and features of Appium.

package/src/resources/submodules/appium/packages/appium/docs/en/intro/clients.md

@@ -0,0 +1,127 @@
+---
+hide:
+  - toc
+
+title: Intro to Appium Clients
+---
+
+For all the reasons discussed in the [main Overview](./appium.md), Appium is based on the [W3C
+WebDriver specification](https://w3c.github.io/webdriver/). This means that
+Appium implements a client-server architecture. The server (consisting of Appium itself along with
+any drivers or plugins you are using for automation) is connected to the devices under test, and
+is actually responsible for making automation happen on those devices. The client (driven by *you*,
+the Appium test author) is responsible for sending commands to the server over the network, and
+receiving responses from the server as a result. These responses can be used to tell whether
+automation commands are successful, or might contain information that you queried about the state
+of the application. This document is a conceptual introduction to the client side of this equation.
+
+!!! info
+
+    For more about the server side of the equation (i.e., how does Appium actually control
+    devices?), check out our [Intro to Appium Drivers](./drivers.md). To skip to a list of links to
+    Appium client libraries, check out the [list of clients](../ecosystem/clients.md).
+
+What sorts of automation commands are available? That is up to the particular driver and plugins
+that you are using in any given session. A standard set of commands would include, for example, the
+following:
+
+- Find Element
+- Click Element
+- Get Page Source
+- Take Screenshot
+
+If you look at these commands in the WebDriver specification, you'll notice that they are not
+defined in terms of any particular programming language. They are not Java commands, or JavaScript
+commands, or Python commands. Instead, they form part of an HTTP API which can be accessed from
+within *any* programming language (or none! you could just use cURL if you want).
+
+So, for example, the `Find Element` command corresponds to an HTTP `POST` request sent to the HTTP
+endpoint `/session/:sessionid/element` (where in this case, `:sessionid` is a placeholder for the
+unique session ID generated by the server in a previous call to `Create Session`).
+
+This information is primarily useful for people developing technology that works with the WebDriver
+spec. It's not particularly useful for people trying to write Appium or Selenium tests. When you
+write an Appium test, you want to use a programming language you're familiar with. Luckily, there
+exist a set of [Appium client libraries](../ecosystem/clients.md)[^1] that take care of the
+responsibility of speaking HTTP to the Appium server. Instead, they expose a set of "native"
+commands for a particular programming language, so that, to the test author, it just feels like
+you're writing Python, or JavaScript, or Java.
+
+As an example, here's the same simple set of Appium commands in five different programming
+languages, using the recommended Appium client binding for each language (note that this is not
+working sample code including all appropriate imports; see each client library's instructions for
+setup and command reference):
+
+=== "JavaScript (Webdriver.io)"
+
+    ```js
+    const element = await driver.$('//*[@text="Foo"]');
+    await element.click();
+    console.log(await element.getText())
+    console.log(await driver.getPageSource())
+    ```
+
+=== "Java"
+
+    ```java
+    WebElement element = driver.findElement(By.Xpath("//*[@text='Foo']"))
+    element.click()
+    System.out.println(element.getText())
+    System.out.println(driver.getPageSource())
+    ```
+
+=== "Python"
+
+    ```py
+    element = driver.find_element(by=By.XPATH, value='//*[@text="Foo"]')
+    element.click()
+    print(element.text)
+    print(driver.page_source)
+    ```
+
+=== "Ruby"
+
+    ```rb
+    element = driver.find_element :xpath, '//*[@text="Foo"]'
+    element.click
+    puts element.text
+    puts driver.page_source
+    ```
+    
+=== "C#"
+
+    ```dotnet
+    AppiumElement element = driver.FindElement(MobileBy.AccessibilityId("Views"));   
+    element.click();
+    System.Console.WriteLine(element.Text);
+    System.Console.WriteLine(driver.PageSource);
+    ```
+    
+Each of these scripts, despite being in different languages, does the same thing under the hood:
+
+1. Call `Find Element` with a `using` parameter of `xpath` and a `value` parameter expressing the
+   XPath query used to find an element. (If you're confused about these terms, you might find an
+   introduction to Appium or Selenium useful)
+2. Call `Click Element` with the ID of the element found in the previous call.
+3. Call `Get Element Text` with the ID of the same element, and print it to the console.
+4. Call `Get Page Source` to retrieve the page/app source and print it to the console.
+
+The only other thing to keep in mind before choosing or using a client is that each client is
+independently maintained. Just because a feature is available in one client, it doesn't mean it's
+available in another client (though all clients support at least the standard W3C protocol plus any
+common appium extensions). Just because one client has a nice set of helper functions, doesn't mean
+another will. Some clients are kept very frequently up to date, and others are not! So when
+thinking about choosing a library, the first consideration is the language you want to use, and the
+second consideration is how full-featured and well-maintained the library is!
+
+To learn how to use an Appium client, visit that client's homepage to learn more. In many cases,
+the Appium client for a given language is built *on top of* the *Selenium* client for that
+language, and so certain Appium clients may only document the features which the Appium client
+added on top of the Selenium client. All that to say, for a full reference, you may need to visit
+both the Appium client documentation as well as the Selenium client documentation.
+
+That's all you need to know about Appium clients! Head over to the
+[Clients](../ecosystem/clients.md) page to check out the current list of clients.
+
+[^1]: These libraries are alternately called "clients", "client libraries", or "client bindings".
+  They all mean the same thing!

package/src/resources/submodules/appium/packages/appium/docs/en/intro/drivers.md

@@ -0,0 +1,188 @@
+---
+title: Intro to Appium Drivers
+---
+
+As the [main Overview](./appium.md) makes clear, "drivers" are basically Appium's answer to the
+question, "how do we support automation of multiple, unrelated platforms?" In this doc we'll get
+into a little more detail about how drivers work. The specific details of how drivers work probably
+don't matter too much for you, unless you're planning on writing your own driver or contributing to
+an existing driver (things we hope you do!).
+
+The main benefit in understanding a bit more of how drivers work is that being aware of the typical
+complexity or the typical driver architecture will inform your debugging process when you
+inevitably run into an issue in one of your tests.
+
+## Interface Implementations
+
+At the most basic level, drivers are simply Node.js classes that extend a special class included in
+Appium, called `BaseDriver`. You could have something very close to a "working" driver, with these
+very simple lines of code:
+
+```js
+import BaseDriver from '@appium/base-driver'
+
+class MyNewDriver extends BaseDriver {
+}
+```
+
+This empty driver doesn't *do* anything, but you could wrap it up in a Node.js module, add a few
+Appium-related fields to the module's manifest (`package.json`), and then install it using `appium
+driver install`.
+
+So, from a technical perspective, an Appium driver is just a bit of code that inherits from some
+other Appium code. That's it! Now, inheriting from `BaseDriver` actually gives us a lot, because
+`BaseDriver` is essentially an encapsulation of the entire WebDriver protocol. So all a driver
+needs to do something useful is to *implement* Node.js methods with names corresponding to
+their WebDriver protocol equivalents.
+
+So let's say I wanted to do something with this empty driver; first I have to decide which
+WebDriver command I want to implement. For our example, let's take the [Navigate
+To](https://w3c.github.io/webdriver/#navigate-to) WebDriver command. Leave aside for the moment
+what I want to have the driver *do* when this command is executed. To tell Appium the driver can
+handle the command, all we have to do is define a method like this in our driver class:[^1]
+
+```js
+async setUrl(url) {
+    // do whatever we want here
+}
+```
+
+[^1]: You might notice that `setUrl` doesn't look anything like `Navigate To`, so how did we know
+  to use it rather than some other random string? Well, Appium's WebDriver-protocol-to-method-name
+  mapping is defined in a special file within the `@appium/base-driver` package called
+  [routes.js](https://github.com/appium/appium/blob/master/packages/base-driver/lib/protocol/routes.js).
+  So if you're writing a driver, this is where you would go to figure out what method names to use
+  and what parameters to expect. Or you could look at the source for any of the main Appium
+  drivers!
+
+That's it! How we actually implement the command is totally up to us, and depends on the
+platform(s) we want to support. Here are some different example implementations of this command for
+different platforms:
+
+- Browsers: execute some JavaScript to set `window.location.href`
+- iOS apps: launch an app using a deep link
+- Android apps: launch an app using a deep link
+- React apps: load a specific route
+- Unity: go to a named scene
+
+So you can see there can be a lot of differences between how drivers implement the same WebDriver
+command across platforms.[^2] What is the *same*, though, is how they express that they can handle
+a protocol command.
+
+[^2]: Of course, we want to keep the semantics as similar as possible, but in the world of iOS, for
+  example, launching an app via a deep link (a URL with a special app-specific scheme) is about as
+  close as we are going to get to navigating to a web URL.
+
+We're going into this great amount of detail (which you don't need to remember, by the way),
+because it's important to stress the point that an Appium driver is not inherently anything in
+particular, other than a bit of JS code that can handle WebDriver protocol commands. Where you go
+from there is up to you, the driver author!
+
+## Automation mapping
+
+But *typically* what driver authors want to do is to provide automation behaviours for a given
+platform(s) that are semantically very similar to the the WebDriver spec implementations for
+browsers. When you want to find an element, you should get a reference to a UI element. When you
+want to click or tap that element, the resulting behaviour should be the same as if a person were
+to click or tap on the element. And so on.
+
+So the real challenge for driver authors is not how to work with the WebDriver protocol (because
+`BaseDriver` encapsulates all that for you), but how to make the actual automation happen on the
+target platform. Every driver relies on its own set of underlying technologies here. As mentioned
+in the [Overview](index.md), the iOS driver uses an Apple technology called
+[XCUITest](https://developer.apple.com/documentation/xctest/xcuielement). These underlying
+automation technologies usually have proprietary or idiosyncratic APIs of their own. Writing
+a driver becomes the task of mapping the WebDriver protocol to this underlying API (or sometimes
+a set of different underlying APIs--for example, the UiAutomator2 driver relies not only on the
+[UiAutomator2](https://developer.android.com/training/testing/other-components/ui-automator)
+technology from Google, but also functions only available through
+[ADB](https://developer.android.com/tools/adb), as well as functions only available
+via the Android SDK inside a helper app). Tying it all together into a single, usable, WebDriver
+interface is the incredibly useful (but incredibly challenging) art of driver development!
+
+## Multi-level architecture
+
+In practice, this often results in a pretty complex architecture. Let's take iOS for example again.
+The XCUITest framework (the one used by the Appium driver) expects code that calls it to be written
+in Objective-C or Swift. Furthermore, XCUITest code can only be run in a special mode triggered by
+Xcode (and directly or indirectly, the Xcode command line tools). In other words, there's no
+straightforward way to go from a Node.js function implementation (like `setUrl()` above) to
+XCUITest API calls.
+
+What the XCUITest driver authors have done is instead to split the driver into two parts: one part
+written in Node.js (the part which is incorporated into Appium and which initially handles the
+WebDriver commands), and the other part written in Objective-C (the part which actually gets run on
+an iOS device and makes XCUITest API calls). This makes interfacing with XCUITest possible, but
+introduces the new problem of coordination between the two parts.
+
+The driver authors could have chosen any of a number of very different strategies to model the
+communication between the Node.js side and the Objective-C side, but at the end of the day decided
+to use ... the WebDriver protocol! That's right, the Objective-C side of the XCUITest driver is
+itself a WebDriver implementation, called
+[WebDriverAgent](https://github.com/appium/webdriveragent).[^3]
+
+[^3]: You could in theory, therefore, point your WebDriver client straight to WebDriverAgent and
+  bypass Appium entirely. This is usually not convenient, however, for a few reasons:
+
+  - The Appium XCUITest driver builds and manages WebDriverAgent for you, which can be a pain and
+    involves the use of Xcode.
+  - The XCUITest driver does lots more than what can be done by WebDriverAgent, for example working
+    with simulators or devices, installing apps, and the like.
+
+The moral of the story is that driver architectures can become quite complicated and multilayered,
+due to the nature of the problem we're trying to solve. It also means it can be difficult sometimes
+to tell where in this chain of technologies something has gone wrong, if you run into a problem
+with a particular test. With the XCUITest world again, we have something like the following set of
+technologies all in play at the same time:
+
+- Your test code (in its programming language) - owned by you
+- The Appium client library - owned by Appium
+- The Selenium client library - owned by Selenium
+- The network (local or Internet)
+- The Appium server - owned by Appium
+- The Appium XCUITest driver - owned by Appium
+- WebDriverAgent - owned by Appium
+- Xcode - owned by Apple
+- XCUITest - owned by Apple
+- iOS itself - owned by Apple
+- macOS (where Xcode and iOS simulators run) - owned by Apple
+
+It's a pretty deep stack!
+
+## Proxy mode
+
+There's one other important architectural aspect of drivers to understand. It can be exemplified
+again by the XCUITest driver. Recall that we just discussed how the two "halves" of the XCUITest
+driver both speak the WebDriver protocol---the Node.js half clicks right into Appium's WebDriver
+server, and the Objective-c half (WebDriverAgent) is its own WebDriver implementation.
+
+This opens up the possibility of Appium taking a shortcut in certain cases. Let's imagine that the
+XCUITest driver needs to implement the `Click Element` command. The internal code of this
+implementation would look something like taking the appropriate parameters and constructing an HTTP
+request to the WebDriverAgent server. In this case, we're basically just reconstructing the
+client's original call to the Appium server![^4] So there's really no need to even write a function
+implementing the `Click Element` command. Instead, the XCUITest driver can just let Appium know
+that this command should be proxied directly to some other WebDriver server.
+
+[^4]: It's not *exactly* the same call, because the Appium server and the WebDriverAgent server
+  will generate different session IDs, but these differences will be handled transparently.
+
+If you're not familiar with the concept of "proxying," in this case it just means that the XCUITest
+driver will not be involved at all in handling the command. Instead it will merely be repackaged
+and forwarded to WebDriverAgent at the protocol level, and WebDriverAgent's response will likewise
+be passed back directly to the client, without any XCUITest driver code seeing it or modifying it.
+
+This architectural pattern provides a nice bonus for driver authors who choose to deal with the
+WebDriver protocol everywhere, rather than constructing bespoke protocols. It also means that
+Appium can create wrapper drivers for any other existing WebDriver implementation very easily. If
+you look at the [Appium Safari driver](https://github.com/appium/appium-safari-driver) code, for
+example, you'll see that it implements basically no standard commands, because all of these are
+proxied directly to an underlying SafariDriver process.
+
+It's important to understand that this proxying business is sometimes happening under the hood,
+because if you're ever diving into some open source driver code trying to figure out where
+a command is implemented, you might be surprised to find no implementation at all in the Node.js
+driver code itself! In that case, you'll need to figure out where commands are being proxied to so
+you can look there for the appropriate implementation.
+
+OK, that's enough for this very detailed introduction to drivers!