appium-mcp 0.0.1 → 1.1.5

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

@@ -0,0 +1,43 @@
+---
+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/ja/index.md

@@ -0,0 +1,55 @@
+---
+hide:
+  - navigation
+  - toc
+
+title: ようこそ
+---
+
+<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>
+
+Appiumのドキュメントにようこそ！ Appiumはオープンソースプロジェクトであり、そのエコシステムは多様なプラットフォーム、例えばモバイル（iOS・Android・Tizen）やブラウザ（Chrome・Firefox・Safari）、デスクトップ（macOS・Windows）、TV（Roku・tvOS・Android TV・Samsung）に対するUI自動化を支援するために設計されています。
+
+<div style="text-align: center; margin-top: 2rem; font-style: italic;">
+  Appiumはパートナーのサポートに非常に感謝しています！ （私たちのスポンサーシップと貢献者への報酬の枠組みは<a
+  href="https://github.com/appium/appium/blob/master/GOVERNANCE.md#sponsorship">こちら</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>
+
+## ドキュメントを検索する
+
+<div class="grid cards" markdown>
+
+- [**Introduction**](./intro/index.md) を読んで、主要なコンセプトを理解してください
+- [**Quickstart**](./quickstart/index.md) を通して、基本的なAndroidテストを用意、実行します。
+- 使用するドライバ、クライアント、プラグインの一覧については、 [**Ecosystem**](./ecosystem/index.md) ページを参照してください。
+- 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
+- 独自の Appium 拡張を作成するには、 [**Developer**](./developing/index.md) ドキュメントを参考にしてください。
+- 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/ja/intro/appium.md

@@ -0,0 +1,191 @@
+---
+title: How Does Appium Work?
+---
+
+「はじめに」でも言及したとおり、Appiumはオープンソースプロジェクトであり、多くのアプリケーションプラットフォームのUI自動化を助けるために設計された関係するソフトウェアのエコシステムです。 Appium 2.0のリリースにより、Appiumは以下の主要な目標を達成します：[^1]
+
+- 標準化されたAPIにより、クロスプラットフォームながらもプラットフォーム固有の自動化を可能とする
+- 様々なプログラミング言語からこのAPIを呼び出すことができる
+- コミュニティ間で開発された便利なAppium拡張（Appium extension）を利用できるようになる
+
+[^1]: これらの主要な目的達成のため、私たちは二次的な目標や原則に沿っています。Appium拡張（Appium extension）の開発者にも同様に推奨するものです。
+
+    - 可能な限り、オープンソースを活用し、オープンソースに貢献もする
+    - 可能な限り、開発元から提供されるプラットフォーム固有のツールを使用する
+    - 可能な限り、テスト対象に変更を必要としない自動化ツールを使用する（専用ビルドを必要とするような追加のSDKやテスト対象版と製品版とで差異があることは好ましくない）
+    - 可能な限り、新しい独自のものを作るより既にある標準のものを使う
+
+したがって、iOSやAndroidといったいかなるアプリプラットフォームに対しても、 Appiumは開発者やテスターにそのプラットフォームにおけるUI自動化コードを一つの統一されたAPIで記述できるようにします。 Appiumの目標を実現するために私たちは多くの疑問に答える必要があります。
+
+- "一つの統一された" APIとは何か？
+- どのように私たちはそのAPIを特定のプラットフォームにおける自動化としての振る舞いに対応させているか？
+- どのように私たちは複数のよく知られるプログラミング言語から利用可能にしているか？
+
+iOSとAndroidだけでなくより多くのアプリプラットフォームが存在していることを考えると、その背景には別の、より大きな疑問が潜んでいます。
+
+- どのようにして_全ての_プラットフォームに対して自動化を実現するか？
+
+これらの疑問へのAppiumの答えを知ることは、Appiumが何かを学ぶ最短の方法ではないかもしれませんが、確かな道になります。 では、見ていきましょう。
+
+## 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. 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 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 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.
+
+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 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). 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/ja/intro/clients.md

@@ -0,0 +1,139 @@
+---
+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. 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/ja/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 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!