@appium/mcp-documentation 1.0.3 → 1.0.4

package/src/resources/submodules/appium/packages/appium/docs/zh/quickstart/test-dotnet.md

@@ -0,0 +1,99 @@
+---
+hide:
+  - toc
+
+title: 编写测试 (.NET)
+---
+
+[Appium .NET Client](https://github.com/appium/dotnet-client/) 是
+官方的 Appium C# 客户端。 这个驱动程序是 Selenium C# 客户端的扩展。 它具有常规驱动程序的所有功能，但在之上添加了 Appium 特定的方法。 该驱动程序在公共 NuGet Gallery 上作为 [Appium.WebDriver](https://www.nuget.org/packages/Appium.WebDriver/) 提供。
+
+现在，我们进入目录并创建一个新的 [NUnit](https://nunit.org/) 项目。 我们还将添加对 Appium.Net 驱动程序和其他依赖项的引用。
+
+```bash
+cd dotnet-client
+dotnet new nunit --name appiumtest
+
+cd appiumtest
+
+# 这将安装最新的 5.x 版本
+dotnet add package Appium.WebDriver  --prerelease
+dotnet add package Newtonsoft.Json --version 13.0.3
+```
+
+完成后，您的项目应该有一个占位符文件 `UnitTest1.cs`。 我们将替换代码以包含 OpenQA 命名空间、驱动程序的初始化以及实际测试。
+
+```C# title="UnitTest1.cs"
+using OpenQA.Selenium;
+using OpenQA.Selenium.Appium;
+using OpenQA.Selenium.Appium.Android;
+using OpenQA.Selenium.Appium.Enums;
+
+namespace appiumtest;
+
+public class Tests
+{
+    private AndroidDriver _driver;
+
+    [OneTimeSetUp]
+    public void SetUp()
+    {
+        var serverUri = new Uri(Environment.GetEnvironmentVariable("APPIUM_HOST") ?? "http://127.0.0.1:4723/");
+        var driverOptions = new AppiumOptions() {
+            AutomationName = AutomationName.AndroidUIAutomator2,
+            PlatformName = "Android",
+            DeviceName = "Android Emulator",
+        };
+
+        driverOptions.AddAdditionalAppiumOption("appPackage", "com.android.settings");
+        driverOptions.AddAdditionalAppiumOption("appActivity", ".Settings");
+        // NoReset assumes the app com.google.android is preinstalled on the emulator
+        driverOptions.AddAdditionalAppiumOption("noReset", true);
+
+        _driver = new AndroidDriver(serverUri, driverOptions, TimeSpan.FromSeconds(180));
+        _driver.Manage().Timeouts().ImplicitWait = TimeSpan.FromSeconds(10);
+    }
+
+    [OneTimeTearDown]
+    public void TearDown()
+    {
+        _driver.Dispose();
+    }
+
+    [Test]
+    public void TestFindApps()
+    {
+        _driver.StartActivity("com.android.settings", ".Settings");
+        _driver.FindElement(By.XPath("//*[@text='Apps']")).Click();
+    }
+}
+```
+
+!!! 备注
+
+```
+这份指南的范围不包括对 dotnet 客户端库或此处发生的一切进行完整说明，因此我们暂时不对代码本身进行详细解释。您可能需要特别阅读 Appium [Capabilities](../guides/caps.md)，以及熟悉 [dotnet 客户端驱动程序文档](https://github.com/appium/dotnet-client/) 以获得对您看到的各种 API 命令及其目的的更全面解释。
+```
+
+基本上，此代码执行以下操作：
+
+1. 定义一组"Capabilities"（参数）发送到 Appium 服务器，以便 Appium 知道您想要自动化什么。 有些参数可以使用环境变量覆盖。
+2. 在内置的 Android 设置应用上启动 Appium 会话。
+3. 查找"Apps"列表项并点击它。
+4. 结束 Appium 会话。
+
+就是这样！ 让我们试试。 在运行测试之前，请确保在另一个终端会话中运行 Appium 服务器，否则您会收到无法连接的错误。 然后，您可以执行脚本：
+
+```bash
+dotnet test
+
+# 示例输出：
+# Starting test execution, please wait...
+# A total of 1 test files matched the specified pattern.
+
+# Passed!  - Failed:     0, Passed:     1, Skipped:     0, Total:     1, Duration: 323 ms - appiumtest.dll (net7.0)
+```
+
+如果一切顺利，您将看到设置应用打开并在模拟器中导航到"Apps"视图，然后应用再次关闭。
+
+恭喜，您已经开始了 Appium 之旅！ 继续阅读一些 [后续步骤](./next-steps.md) 以进行探索。

package/src/resources/submodules/appium/packages/appium/docs/zh/quickstart/test-java.md

@@ -0,0 +1,20 @@
+---
+hide:
+  - toc
+
+title: 编写测试 (Java)
+---
+
+Appium 团队维护了一个官方的 [客户端](https://github.com/appium/java-client) 用于 Java 编程语言。
+它建立在 [Selenium](https://github.com/SeleniumHQ/selenium) 之上。
+您也可以在 Kotlin 项目中使用此客户端。
+
+按照 [将 Appium Java 客户端添加到您的测试框架](https://github.com/appium/java-client#add-appium-java-client-to-your-test-framework) 教程将库连接到您的测试框架源代码。
+
+Appium Java 客户端具有专用类来支持大多数官方 Appium 驱动程序。 对于其他驱动程序，您可以简单地使用 [AppiumDriver](https://github.com/appium/java-client/blob/master/src/main/java/io/appium/java_client/AppiumDriver.java) 类
+或从中构建自定义派生类。 查看 [驱动程序支持](https://github.com/appium/java-client#drivers-support) 文章以了解当前驱动程序类实现的更多信息。
+
+按照 [使用示例](https://github.com/appium/java-client#usage-examples) 文章以了解
+如何从您的测试框架调用 Java 客户端功能。
+
+一旦您成功运行了一个测试，您可以继续阅读一些 [后续步骤](./next-steps.md) 以进行探索。

package/src/resources/submodules/appium/packages/appium/docs/zh/quickstart/test-js.md

@@ -0,0 +1,62 @@
+---
+hide:
+  - toc
+
+title: 编写测试 (JS)
+---
+
+要在 JavaScript (Node.js) 中编写 Appium 测试，我们需要选择一个与 Appium 兼容的客户端库。 维护最好的库，也是 Appium 团队推荐使用的，是 [WebdriverIO](https://webdriver.io)，所以让我们使用它。 由于我们已经安装了 Appium，我们知道我们的 Node 和 NPM 已经满足要求。 所以在您的计算机上某个地方创建一个新的项目目录，然后在其中初始化一个新的 Node.js 项目：
+
+```bash
+npm init
+```
+
+提示中输入什么并不重要，只要最终得到一个有效的 `package.json`。
+
+现在，通过 NPM 安装 `webdriverio` 包：
+
+```bash
+npm i --save-dev webdriverio
+```
+
+完成后，您的 `package.json` 文件应该包含如下部分：
+
+```json title="package.json"
+--8<-- "./sample-code/quickstarts/js/package.json"
+```
+
+现在是编写测试本身的时候了。 创建一个名为 `test.js` 的新文件，内容如下：
+
+```js title="test.js"
+--8<-- "./sample-code/quickstarts/js/test.js"
+```
+
+!!! note
+
+```
+这份指南的范围不包括对 WebdriverIO 客户端库或此处发生的一切进行完整说明，因此我们暂时不对代码本身进行详细解释。您可能需要特别阅读 Appium [Capabilities](../guides/caps.md)，以及熟悉优秀的 [WebdriverIO 文档](https://webdriver.io/docs/gettingstarted) 以获得对您看到的各种 API 命令及其目的的更全面解释。
+```
+
+!!! note
+
+```
+示例代码可从 [GitHub Appium 仓库](https://github.com/appium/appium/tree/master/packages/appium/sample-code/quickstarts/js) 获取。
+```
+
+基本上，此代码执行以下操作：
+
+1. 定义一组"Capabilities"（参数）发送到 Appium 服务器，以便 Appium 知道您想要自动化什么。
+2. 在内置的 Android 设置应用上启动 Appium 会话。
+3. 查找"Apps"列表项并点击它。
+4. 暂停片刻纯粹为了视觉效果。
+5. 结束 Appium 会话。
+
+就是这样！ 让我们试试。 在运行测试之前，请确保在另一个终端会话中运行 Appium 服务器，否则您会收到无法连接的错误。 然后，您可以执行脚本：
+
+```bash
+node test.js
+```
+
+如果一切顺利，您将看到设置应用打开并导航到"Apps"视图，然后应用再次关闭。
+
+恭喜，您已经开始了 Appium 之旅！ 继续阅读一些 [后续步骤](./next-steps.md) 以进行探索。

package/src/resources/submodules/appium/packages/appium/docs/zh/quickstart/test-py.md

@@ -0,0 +1,57 @@
+---
+hide:
+  - toc
+
+title: 编写测试 (Python)
+---
+
+[Appium Python Client](https://github.com/appium/python-client) 是
+官方的 Python Appium 客户端，可通过 pypi 以 [Appium-Python-Client](https://pypi.org/project/Appium-Python-Client/) 包名获取。
+它继承自 [Selenium Python Binding](https://pypi.org/project/selenium/)，
+因此安装 Appium Python Client 包括 selenium 绑定。
+
+```bash
+pip install Appium-Python-Client
+```
+
+此示例使用 Python 的内置 `unittest` 模块，您也可以使用任何您想要的 Python 测试框架。
+Appium Python 客户端自动添加 `appium:` 前缀。
+您通常不需要担心前缀。
+
+```python title="test.py"
+--8<-- "./sample-code/quickstarts/py/test.py"
+```
+
+!!! note
+
+```
+这份指南的范围不包括对 Python 客户端库或此处发生的一切进行完整说明，因此我们暂时不对代码本身进行详细解释。
+
+- 您可能需要特别阅读 Appium [Capabilities](../guides/caps.md)。
+- Python Client GitHub 仓库中的 [功能测试代码](https://github.com/appium/python-client/tree/master/test/functional) 应该有助于找到更多工作示例。
+- [文档](https://appium.github.io/python-client-sphinx/) 也有助于找到 Appium Python Client 中定义的方法。
+```
+
+!!! note
+
+```
+示例代码可从 [GitHub Appium 仓库](https://github.com/appium/appium/tree/master/packages/appium/sample-code/quickstarts/py) 获取。
+```
+
+基本上，此代码执行以下操作：
+
+1. 定义一组"Capabilities"（参数）发送到 Appium 服务器，以便 Appium 知道您想要自动化什么。
+2. 在内置的 Android 设置应用上启动 Appium 会话。
+3. 查找"Apps"列表项并点击它。
+4. 暂停片刻纯粹为了视觉效果。
+5. 结束 Appium 会话。
+
+就是这样！ 让我们试试。 在运行测试之前，请确保在另一个终端会话中运行 Appium 服务器，否则您会收到无法连接的错误。 然后，您可以执行脚本：
+
+```bash
+python test.py
+```
+
+如果一切顺利，您将看到设置应用打开并导航到"Apps"视图，然后应用再次关闭。
+
+恭喜，您已经开始了 Appium 之旅！ 继续阅读一些 [后续步骤](./next-steps.md) 以进行探索。

package/src/resources/submodules/appium/packages/appium/docs/zh/quickstart/test-rb.md

@@ -0,0 +1,80 @@
+---
+hide:
+  - toc
+
+title: 编写测试 (Ruby)
+---
+
+[AppiumLib](https://github.com/appium/ruby_lib) 和 [AppiumLibCore](https://github.com/appium/ruby_lib_core)（**推荐**）是 Ruby 中的官方 Appium 客户端库，可通过 gem 以 [appium_lib](https://rubygems.org/gems/appium_lib) 和 [appium_lib_core](https://rubygems.org/gems/appium_lib_core) 包名获取。 appium_lib_core 继承自 Selenium Ruby Binding，而 appium_lib 继承自 appium_lib_core，因此安装这些库包括 selenium 绑定。 如果您需要一个不太复杂的客户端解决方案，我们推荐 `appium_lib_core`。 `appium_lib` 有一些核心没有的有用方法，但代价是更大的复杂性和可能在最新环境中不工作的历史方法。
+
+作为第一步，让我们初始化一个 Gemfile 来管理依赖项：
+
+```bash
+bundle init
+```
+
+然后，您可以如下添加 Appium Ruby Client 依赖项：
+
+```bash
+bundle add appium_lib_core
+# or
+# bundle add appium_lib
+```
+
+下面的测试代码示例使用 `test-unit` 模块，因此请运行：
+
+```bash
+bundle add test-unit
+```
+
+一旦这些步骤完成，您的 `Gemfile` 文件应该包含：
+
+```ruby title="Gemfile"
+--8<-- "./sample-code/quickstarts/rb/Gemfile"
+```
+
+`appium_lib_core` 是作为 Appium 客户端的主要部分。
+`appium_lib` 有各种辅助方法，但驱动程序实例通常被设计为全局变量使用。 它可能导致处理实例的问题。
+`appium_lib_core` 没有这样的全局变量。
+
+此示例使用 `appium_lib_core` 和 `test-unit` gem 模块。
+在 `appium_lib` 中的测试代码应该类似。
+
+```ruby title="test.rb"
+--8<-- "./sample-code/quickstarts/rb/test.rb"
+```
+
+!!! note
+
+```
+这份指南的范围不包括对 Ruby 客户端库或此处发生的一切进行完整说明，因此我们暂时不对代码本身进行详细解释。
+
+- 您可能需要特别阅读 Appium [Capabilities](../guides/caps.md)。
+- appium_lib_core GitHub 仓库中的 [功能测试代码](https://github.com/appium/ruby_lib_core/tree/master/test/functional) 应该有助于找到更多工作示例。
+- 文档 [appium_lib_core](https://www.rubydoc.info/github/appium/ruby_lib_core) 和 [appium_lib](https://www.rubydoc.info/github/appium/ruby_lib) 也有助于找到可用方法。
+```
+
+!!! note
+
+```
+示例代码可从 [GitHub Appium 仓库](https://github.com/appium/appium/tree/master/packages/appium/sample-code/quickstarts/rb) 获取。
+```
+
+基本上，此代码执行以下操作：
+
+1. 定义一组"Capabilities"（参数）发送到 Appium 服务器，以便 Appium 知道您想要自动化什么。
+2. 在内置的 Android 设置应用上启动 Appium 会话。
+3. 查找"Apps"列表项并点击它。
+4. 暂停片刻纯粹为了视觉效果。
+5. 结束 Appium 会话。
+
+就是这样！ 让我们试试。 在运行测试之前，请确保在另一个终端会话中运行 Appium 服务器，否则您会收到无法连接的错误。 然后，您可以执行脚本：
+
+```bash
+# 如果您的环境尚未运行安装命令，请先运行 "bundle install"。
+bundle exec ruby test.rb
+```
+
+如果一切顺利，您将看到设置应用打开并导航到"Apps"视图，然后应用再次关闭。
+
+恭喜，您已经开始了 Appium 之旅！ 继续阅读一些 [后续步骤](./next-steps.md) 以进行探索。

package/src/resources/submodules/appium/packages/appium/docs/zh/quickstart/uiauto2-driver.md

@@ -0,0 +1,119 @@
+---
+title: 安装 UiAutomator2 驱动程序
+---
+
+除非您有[驱动程序](../intro/drivers.md)，否则您无法使用 Appium 做太多事情，驱动程序是一个允许 Appium 自动化特定平台的接口。
+
+!!! info
+
+```
+对于这个快速入门指南，我们将在 Android 平台上自动化一个应用，因为通过 Appium 进行 Android 自动化的系统要求与 Appium 本身相同（而 iOS 驱动程序，则要求您使用 macOS）。
+```
+
+我们要使用的驱动程序称为 [UiAutomator2 驱动程序](https://github.com/appium/appium-uiautomator2-driver)。 请访问该驱动程序的文档并将其加入书签，因为它将成为未来宝贵的参考。
+
+## 设置 Android 自动化要求
+
+根据驱动程序，除了工作 Appium 服务器，我们还需要设置以下内容：
+
+### Android SDK
+
+- 设置 Android SDK 的最简单方法是下载 [Android Studio](https://developer.android.com/studio)。
+  我们需要使用其 SDK 管理器（_设置 -> 语言和框架 -> Android SDK_）下载以下项目：
+  - Android SDK 平台（选择我们想要自动化的任何 Android 平台，例如 API 级别 30）
+  - Android SDK 平台工具
+- 如果您愿意，您也可以在没有 Android Studio 的情况下下载这些项目：
+  - Android SDK 平台可以使用包含在 [Android 命令行工具](https://developer.android.com/studio#command-line-tools-only) 中的 `sdkmanager` 下载
+  - [Android SDK 平台工具](https://developer.android.com/tools/releases/platform-tools)
+- 设置 `ANDROID_HOME` 环境变量指向安装 Android SDK 的目录。 您通常可以在 Android Studio SDK 管理器中找到此目录的路径。 它将包含 `platform-tools` 和其他目录。
+
+### Java JDK
+
+- 安装 Java JDK（对于最新的 Android API 级别，需要 JDK 9，否则请用 JDK 8）。 您可以从 [Oracle](https://jdk.java.net/) 或 [Adoptium](https://adoptium.net/en-GB/temurin/releases/) 下载此软件。
+  确保您获得 JDK 而不是 JRE。
+- 设置 `JAVA_HOME` 环境变量指向 JDK 主目录。 它将包含 `bin`、`include` 和其他目录。
+
+### 准备设备
+
+- 如果使用模拟器，使用 Android Studio 创建和启动 Android 虚拟设备 (AVD)。
+  您可能需要下载要创建的模拟器的 API 级别的系统映像。 使用 Android Studio 中的 AVD 创建向导通常是完成所有这些的最简单方法。
+- 如果使用真实设备，您应该为其设置[开发者模式并启用 USB 调试](https://developer.android.com/studio/debug/dev-options)。
+- 连接模拟器或设备后，您可以运行 `adb devices`（adb位于 `$ANDROID_HOME/platform-tools/adb`）来验证您的设备是否显示为已连接。
+
+一旦您的设备在 `adb` 中显示为已连接，并且您验证了环境变量设置正确，您应该准备好了！ 如果您在这些步骤中的任何一个遇到问题，请参考驱动程序文档，或根据需要参考各种 Android 或 Java 文档站点。
+
+恭喜：无论您是否打算这样做，您现在已经在系统上设置了 Android 开发者工具链，所以如果您愿意，可以开始制作 Android 应用！
+
+## 安装驱动程序本身
+
+### 标准安装
+
+像所有 Appium 驱动程序一样，UiAutomator 2 驱动程序通过 [Appium 扩展 CLI](../reference/cli/extensions.md) 安装。
+由于 UiAutomator 2 由核心 Appium 团队维护，它有一个“官方”驱动程序名称（`uiautomator2`），这使得安装更简单。
+
+在安装之前，确保您的 Appium 服务器_未_运行（如果正在运行，请用 _Ctrl-C_ 退出）。
+然后运行以下命令：
+
+```bash
+appium driver install uiautomator2
+```
+
+它应该产生看起来像这样的输出：
+
+```
+Attempting to find and install driver 'uiautomator2'
+✔ Installing 'uiautomator2' using NPM install spec 'appium-uiautomator2-driver'
+Driver uiautomator2@2.0.5 successfully installed
+- automationName: UiAutomator2
+- platformNames: ["Android"]
+```
+
+注意安装过程如何指定驱动程序的适用平台（在这里选 `Android`），以及必须用于在 Appium 会话期间选择此驱动程序的自动化名称（`appium:automationName` [能力](../guides/caps.md)）（在这里选 `UiAutomator2`）。
+
+!!! note
+
+```
+在这个快速入门中，我们使用了 [CLI扩展](../reference/cli/extensions.md) 来安装 UiAutomator 2 驱动程序，但如果您将 Appium 纳入 Node.js 项目，您可能更喜欢使用 `npm` 来管理 Appium 及其连接的驱动程序。要了解更多关于此技术的信息，请访问关于[管理 Appium 扩展](../guides/managing-exts.md)的指南。
+```
+
+### 批量安装
+
+您可能希望将 Appium 与多个驱动程序一起使用。 一种方法是为每个单独的驱动程序运行 `appium driver install <driver-name>`，但您也可以一次性安装多个驱动程序：
+
+```
+appium setup
+```
+
+运行此命令将安装 Appium 的移动端特定驱动程序：UiAutomator2、[XCUITest](https://appium.github.io/appium-xcuitest-driver/)（仅在运行 macOS 时），以及 [Espresso](https://github.com/appium/appium-espresso-driver)。
+
+您也可以使用此命令批量安装桌面应用程序或桌面浏览器的驱动程序。
+有关更多详细信息，请参考[设置命令文档](../reference/cli/setup.md)。
+
+### 验证安装
+
+UiAutomator2 驱动程序，像所有官方 Appium 驱动程序一样，带有 Appium Doctor 工具，它允许验证是否所有先决条件都已正确设置：
+
+```
+appium driver doctor uiautomator2
+```
+
+本指南专注于基本要求，因此 Appium Doctor 可能建议一个或多个可选修复。 但如果您看到 `0 required fixes needed`，那意味着一切都设置好了！
+
+现在，再次启动 Appium 服务器（运行 `appium`），您应该看到新安装的驱动程序列为可用：
+
+```
+[Appium] Available drivers:
+[Appium]   - uiautomator2@2.0.5 (automationName 'UiAutomator2')
+```
+
+Android 设置完成并安装了 UiAutomator2 驱动程序，准备编写第一个测试吧！ 现在选择您喜欢的语言并试试：
+
+<div class="grid cards" markdown>
+
+- :material-language-javascript: [**JavaScript**](./test-js.md)
+- :material-language-java: [**Java**](./test-java.md)
+- :material-language-python: [**Python**](./test-py.md)
+- :material-language-ruby: [**Ruby**](./test-rb.md)
+- :material-dot-net: [**.NET C#**](./test-dotnet.md)
+
+</div>