Appium 2 へ移行する
このドキュメントは既にAppium 1 を利用している人がAppium 2 に移行するための手引きです。 破壊的変更の一覧や、実行環境・テストコードをAppium 2 互換にするための方法が含まれます。
Appium 2 is the biggest Appium release in over 5 years. It is not focused on changing the automation behavior for any particular platform, but instead re-envisions Appium into an ecosystem of automation tools:
- The core Appium module retains only platform-agnostic functionality
- Functionality for automating specific platforms is moved to separate driver modules
- Functionality for altering/extending Appium is moved to separate plugin modules
同時に、Appiumプロジェクトは多くの古くなったり非推奨となっている機能や依存を取り除こうとしています。
Since Appium 2 is a major architectural change, we do not recommend directly updating your Appium 1 installations to Appium 2. Instead, please uninstall Appium 1 first, and only install Appium 2 afterwards.
破壊的変更¶
Drivers Installed Separately¶
When installing Appium 1, all available drivers would be installed alongside the main Appium server. In Appium 2, due to its modular structure, this is no longer the case - by default, installing it only installs the core Appium server, without any drivers.
When it comes to installing Appium 2 drivers, there are several approaches you can take:
- Add the
--driversflag when installing Appium, for example:
- Use the Appium Extension CLI, for example:
- Use the Appium Setup CLI command (added in Appium
2.6), for example:
Check the Managing Drivers and Plugins guide for more information.
Actions Needed
Driver Installation Path Changed¶
When installing Appium 1, all available drivers would be installed as dependencies of the main
Appium server, in /path/to/appium/node_modules. 例えば、手動でWebDriverAgentをビルドするためのappium-webdriveragentは、/path/to/appium/node_modules/appium-xcuitest-driver/node_modules/appium-webdriveragentでした。
In Appium 2, drivers (and plugins) are installed at the path defined by the APPIUM_HOME
environment variable, whose default value is ~/.appium. So, appium-webdriveragent would now be
located at $APPIUM_HOME/node_modules/appium-xcuitest-driver/node_modules/appium-webdriveragent.
Actions Needed
If your code uses paths to Appium driver files, update it to use the `APPIUM_HOME` environment
variable
Drivers Updated Separately¶
In Appium 1, in order to get updates to your drivers, you would simply wait for those updates to be rolled into a new release of Appium, and then update your Appium version. With Appium 2, since the server and drivers are separate packages, they can release new versions independently from each other - this means that you no longer need to wait for a new Appium server release, but can install the latest driver versions right away.
Checking for driver updates is done by using the Appium Extension CLI:
更新が入手可能であれば、任意のドライバーに対して update コマンドを実行することができます。
Updating the Appium server itself is the same as before:
However, in Appium 2 this process is a lot quicker, since drivers are no longer bundled with the server package.
Actions Needed
Deprecated Packages No Longer Supported¶
The Appium 1 ecosystem included several drivers, clients and other packages that had since been deprecated and replaced with newer packages. Appium 2 no longer includes support for these packages, and it is recommended to migrate to the following replacements:
| Appium 1 Package | Replacement in Appium 2 |
|---|---|
| iOS Driver | XCUITest Driver |
| UiAutomator Driver | UiAutomator2 |
wd Client |
WebdriverIO Client |
| Appium Desktop | Appium Inspector |
Actions Needed
Default Server Base Path Changed¶
In Appium 1, the default Appium server URL was http://localhost:4723/wd/hub, where the /wd/hub
part (the base path) was a legacy convention from Selenium 1. Appium 2 changes the default base
path to /, therefore the default server URL is now http://localhost:4723/.
Actions Needed
In your test scripts, change the base path of the target server URL from `/wd/hub` to `/`.
Alternatively, you can retain the Appium 1 base path by launching Appium with the
`--base-path=/wd/hub` [command-line argument](../cli/args.md).
Server Port 0 No Longer Supported¶
In Appium 1, it was possible to specify --port 0 during server startup, which had the effect of
starting Appium on a random free port. Appium 2 no longer allows this, and requires port values to
be 1 or higher. If you wish to start Appium on a random port, you must now take care of this on
your own prior to launching the server.
Actions Needed
Driver-Specific CLI Options Changed¶
Appium 1 では、特定のドライバに特化したコマンドラインオプションは、すべてAppiumサーバーに中継されていました。 So, for example, --chromedriver-executable was a CLI parameter you could use to
set the Chromedriver location for the UiAutomator2 driver.
In Appium 2, all driver-specific CLI options have been moved to the drivers themselves. However, depending on the driver, these options may now need to be passed in another way:
- Some options can still be passed as different CLI flags, for example:
appium --webdriveragent-port=5000 # Appium 1
appium --driver-xcuitest-webdriveragent-port=5000 # Appium 2
- Some options can now be passed as environment variables, for example:
- Some options can now be passed as capabilities, for example:
appium --chromedriver-executable=/path/to/chromedriver # Appium 1
{"appium:chromedriverExecutable": "/path/to/chromedriver"} # Appium 2
Actions Needed
If you are using driver-specific CLI options, refer to that driver's documentation for how to
apply them in Appium 2
Filepaths No Longer Supported for Some CLI Options¶
In Appium 1, some server command-line options could be invoked by passing a filepath as their value, and Appium would then parse the contents of that file as the actual value for that option. There were four options that supported this:
--nodeconfig--default-capabilities--allow-insecure--deny-insecure
Appium 2 no longer attempts to parse the contents of filepaths passed to these options, and offers two ways to specify the value for these options:
- As strings, directly on the command line
--nodeconfig/--default-capabilities: JSON string--allow-insecure/--deny-insecure: comma-separated list
- In the Appium Configuration file
Actions Needed
If you are using any of the aforementioned CLI options with a filepath value, update your code
to pass the file contents either directly or through the Appium config file
Old Protocols Dropped¶
AppiumのAPIはW3C WebDriver Protocolに基づいており、何年もこのプロトコルをサポートしています。 Before this protocol was designed as a web standard, the JSON Wire Protocol (JSONWP) and Mobile JSON Wire Protocol (MJSONWP) were used instead.
In Appium 1, all of these protocols were supported, so that older Selenium/Appium clients could still communicate with newer Appium servers. Appium 2 removes support for JSONWP/MJSONWP and is now only compatible with the W3C WebDriver Protocol.
Actions Needed
Capabilities Require Vendor Prefix¶
In Appium 1, in order to create a session, you had to specify certain desired capabilities, which would indicate session parameters, e.g. the driver you want to use. Appium 2 retains this behavior and continues to accept desired capabilities (now renamed simply to 'capabilities'), but as part of the W3C WebDriver Protocol specification, all non-standard capabilities are now required to use a vendor prefix.
The list of standard capabilities is described in the WebDriver Protocol specification,
and includes a few commonly used capabilities like browserName and platformName. All other
capabilities must now start with the vendor name and a colon (the vendor prefix), for example,
moz: or goog:. Since most of Appium's capabilities go beyond the standard W3C capabilities,
all of them must include the appium: prefix (unless specified otherwise):
This requirement may or may not be a breaking change for your test suites. Up-to-date versions of
official Appium clients and the Appium Inspector will automatically add the appium: prefix to all
non-standard capabilities, and the same may apply to cloud-based Appium providers.
Additionally, if you are starting a session with multiple Appium-specific capabilities (which will
likely be the case), it may seem repetitive to add the appium: prefix to each individual
capability. To avoid this, you can optionally group up all these capabilities under a single object
capability, appium:options, for example:
=== "Default Approach"
```json
{
"platformName": "iOS",
"browserName": "Safari",
"appium:platformVersion": "14.4",
"appium:deviceName": "iPhone 11",
"appium:automationName": "XCUITest"
}
```
=== "With appium:options"
```json
{
"platformName": "iOS",
"browserName": "Safari",
"appium:options": {
"platformVersion": "14.4",
"deviceName": "iPhone 11",
"automationName": "XCUITest"
}
}
```
Warning
Capabilities included in the `appium:options` object will overwrite capabilities of the same
name that are used outside of this object. Note that cloud provider support for the
`appium:options` syntax may vary.
ケイパビリティの詳細については、Capabilities Guideをご覧ください。
Actions Needed
Add the `appium:` prefix to all Appium-specific capabilities used in your tests, or wrap them
inside an `appium:options` object
Advanced Features Moved to Plugins¶
One of the design goals for Appium 2 is to extract non-core features into special extensions called plugins. Two such features of Appium 1 have been moved to plugins, and are no longer bundled with Appium 2:
| Feature | Plugin Name |
|---|---|
| Image-related features (comparison, search by image, etc...) | images |
| The Execute Driver Script feature | execute-driver |
Actions Needed
If you were using the image-related features and/or the execute driver script feature in Appium
1, first install their plugin(s):
```
appium plugin install images
appium plugin install execute-driver
```
Afterwards, make sure to activate the plugin(s) upon launching the Appium server:
```
appium --use-plugins=images,execute-driver
```
Endpoint Changes¶
A few server endpoints used in Appium 1 were accepting old or unused parameters. Appium 2 removes support for these parameters. The following is a list of these changed endpoints, along with the parameters they no longer accept, as well as the parameters they continue to accept in Appium 2.
POST /session/:sessionId/appium/device/gsm_signal-
signalStrengh -
signalStrength
-
POST /session/:sessionId/appium/element/:elementId/value-
value -
text
-
POST /session/:sessionId/appium/element/:elementId/replace_value-
value -
text
-
Actions Needed
Check your Appium client documentation for the methods using these endpoints, and adjust your
code to only use the accepted parameters
Internal Packages Renamed¶
In Appium 1, the internal dependency packages were each located in their own repository. Appium 2 moves to a monorepo structure and therefore renames many of these packages, for example:
Actions Needed
If you do not directly import Appium packages into your code - none! However, if you do, make
sure to update the names of your Appium package imports!
主な新機能¶
Apart from the breaking changes mentioned above, here are some of the major new features you may wish to take advantage of with Appium 2:
Third-Party Drivers and Plugins¶
You are no longer limited to official drivers or plugins, or ones that the Appium team even knows
about! Developers can now create their own custom drivers or plugins, which can be installed via
Appium's Extension CLI from npm, git, GitHub, or even the local
filesystem. Interested in building a driver or plugin? Check out the
Building Drivers and
Building Plugins guides.
Configuration Files¶
Appiumは、コマンドライン引数に加え、設定ファイル もサポートするようになりました。 Nearly all options or flags that had to be specified on the CLI in Appium 1, can now also be provided in a configuration file. The file can be in JSON, JS, or YAML format. For more information, refer to the Config File Guide.
クラウド・プロバイダーに関する特記事項¶
Most of this guide has applied to Appium end users or developers, but some of the architectural changes in Appium 2 will constitute breaking changes for different Appium service providers. At the end of the day, the maintainer of the Appium server is responsible for installing and exposing the various Appium drivers and plugins that end users may wish to use.
クラウドプロバイダーには、業界と互換性のある方法でユーザーのニーズをサポートするために、私たちのクラウドプロバイダーの能力に関する推奨事項 を十分に読み、理解することをお勧めします！