diff --git a/README.md b/README.md index c322954..908b123 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,9 @@ [![Meta file check](https://github.com/DeNA/Anjin/actions/workflows/metacheck.yml/badge.svg)](https://github.com/DeNA/Anjin/actions/workflows/metacheck.yml) [![openupm](https://img.shields.io/npm/v/com.dena.anjin?label=openupm®istry_uri=https://package.openupm.com)](https://openupm.com/packages/com.dena.anjin/) -This is an autopilot tool for games made with Unity. +Click [日本語](./README_ja.md) for the Japanese page if you need. + +**Anjin** is an autopilot framework for games made with Unity. It consists of the following two elements. 1. A dispatcher that launches the corresponding Agent according to the Scene loaded in the game @@ -12,8 +14,6 @@ It consists of the following two elements. Agents are small, isolated C# scripts that perform specific operations, such as playback of UI operations or monkey tests. In addition to the built-in ones, you can implement and use ones specific to your game title. -Click [日本語](./README_ja.md) for the Japanese page if you need. - ## Installation @@ -134,7 +134,7 @@ Set up a filter to catch abnormal log messages and notify using Reporter.
Handle Error
Report when error message is detected in log
Handle Assert
Report when assert message is detected in log
Handle Warning
Report when warning message is detected in log
-
Ignore Messages
Log messages containing this string will not be reported. Regex is also available.
+
Ignore Messages
Log messages containing this string will not be reported. Regex is also available, and escape is a single backslash (`\`).
@@ -339,7 +339,7 @@ The instance of this Agent (.asset file) can have the following settings. An Agent that can register one child Agent and execute it only once throughout the Autopilot execution period. The second time executions will be skipped. -For example, in a game where the title scene leads to a different path only for the first time or where the user receives a login bonus only for the first time on the home scene, it is possible to construct a scenario in which the title screen is executed as is even if a communication error or the like causes a return to the title scene. +For example, in a game where the title scene leads to a different path only for the first time or where the user receives a login bonus only for the first time on the home scene, it is possible to construct a test scenario in which the title screen is executed as is even if a communication error or the like causes a return to the title scene. The Agent instance (.asset file) can contain the following settings. @@ -352,7 +352,7 @@ The Agent instance (.asset file) can contain the following settings. An Agent that executes one child Agent indefinitely and repeatedly. -Combined with SerialCompositeAgent, it can be used to repeat a scenario many times or to repeat only the last Agent in a scenario. +Combined with SerialCompositeAgent, it can be used to repeat a sequence many times or to repeat a specific Agent. Note that finite iterations are not supported (to use SerialCompositeAgent). This Agent instance (.asset file) can contain the following. @@ -381,7 +381,7 @@ This Agent instance (.asset file) can contain the following. ### EmergencyExitAgent -An Agent that monitors the appearance of the `EmergencyExit` component in the `DeNA.Anjin.Annotations` assembly and clicks on it as soon as it appears. +An Agent that monitors the appearance of the `EmergencyExitAnnotations` component in the `DeNA.Anjin.Annotations` assembly and clicks on it as soon as it appears. This can be used in games that contain behavior that is irregular in the execution of the test scenario, for example, communication errors or "return to title screen" buttons that are triggered by a daybreak. It should always be started at the same time as other Agents (that actually perform game operations). @@ -394,7 +394,7 @@ This can be accomplished with `ParallelCompositeAgent`, but it is easier to set The following Logger types are provided. These can be used as they are, or game-title-specific custom Loggers can be implemented and used. -### Composite Logger +### CompositeLogger A Logger that delegates to multiple loggers. @@ -405,7 +405,7 @@ The instance of this Logger (.asset file) can have the following settings. -### Console Logger +### ConsoleLogger A Logger that outputs to a console. @@ -416,7 +416,7 @@ The instance of this Logger (.asset file) can have the following settings. -### File Logger +### FileLogger A Logger that outputs to a specified file. @@ -436,7 +436,7 @@ The instance of this Logger (.asset file) can have the following settings. The following Reporter types are provided. These can be used as they are, or game-title-specific custom Reporters can be implemented and used. -### Composite Reporter +### CompositeReporter A Reporter that delegates to multiple Reporters. @@ -447,21 +447,30 @@ The instance of this Reporter (.asset file) can have the following settings. -### Slack Reporter +### SlackReporter A Reporter that post report to Slack. The instance of this Reporter (.asset file) can have the following settings.
-
Slack Token
Web API token used for Slack notifications. If omitted, no notifications will be sent. +
Slack Token
OAuth token of Slack Bot used for notifications. If omitted, no notifications will be sent. This setting can be overwritten with the command line argument -SLACK_TOKEN.
-
Slack Channels
Channels to send Slack notifications. If omitted, not notified. Multiple channels can be specified by separating them with commas. - This setting can be overwritten with the command line argument -SLACK_CHANNELS.
-
Mention Sub Team IDs
Comma Separated Team IDs to Mention in Slack Notification Message
-
Add Here In Slack Message
Add @here to Slack notification message. Default is off
+
Slack Channels
Channels to send notifications. If omitted, not notified. Multiple channels can be specified by separating them with commas. + This setting can be overwritten with the command line argument -SLACK_CHANNELS. + The bot must be invited to the channel.
+
Mention Sub Team IDs
Comma Separated Team IDs to mention in notification message
+
Add Here In Slack Message
Add @here to notification message. Default is off
+You can create a bot on the following page: +[Slack API: Applications](https://api.slack.com/apps) + +The bot needs the following permissions: + +- chat:write +- files:write + ## Implementation of game-title-specific @@ -531,7 +540,7 @@ Please note that this will be included in the release build due to the way it wo The `GameObject` to which this component is attached avoids manipulation by the `UGUIMonkeyAgent`. -### EmergencyExit +### EmergencyExitAnnotations When a `Button` to which this component is attached appears, the `EmergencyExitAgent` will immediately attempt to click on it. It is intended to be attached to buttons that are irregular in the execution of the test scenario, such as the "return to title screen" button due to a communication error or a daybreak. @@ -672,10 +681,22 @@ MIT License ## How to contribute Open an issue or create a pull request. - Be grateful if you could label the pull request as `enhancement`, `bug`, `chore`, and `documentation`. See [PR Labeler settings](.github/pr-labeler.yml) for automatically labeling from the branch name. +The general policy for accepting new features is as follows: + +- All built-in features can be easily configured in the Unity Editor's Inspector window. +- Avoid adding features to the `Autopilot` class as much as possible, and consider expanding it with Agents, etc. +- Refrain from adding non-general-purpose agents. Consider publishing them on your blog or Gist or placing them in Samples. + + +The following feature requests/ pull requests will be rejected because they go against the concept of Anjin: + +- Ability to run multiple test scenarios (AutopilotSettings) in succession. Use the feature to run from Play Mode tests. +- Ability to specify "Start Scene" in AutopilotSettings. We recommend creating a test scenario that can be run from any Scene. + + ## How to development Add this repository as a submodule to the Packages/ directory in your project. diff --git a/README_ja.md b/README_ja.md index 9af01c6..d2cb057 100644 --- a/README_ja.md +++ b/README_ja.md @@ -3,7 +3,9 @@ [![Meta file check](https://github.com/DeNA/Anjin/actions/workflows/metacheck.yml/badge.svg)](https://github.com/DeNA/Anjin/actions/workflows/metacheck.yml) [![openupm](https://img.shields.io/npm/v/com.dena.anjin?label=openupm®istry_uri=https://package.openupm.com)](https://openupm.com/packages/com.dena.anjin/) -Unity製ゲームのオートパイロットツールです。 +Click [English](./README.md) for English page if you need. + +**Anjin**は、Unity製ゲーム向けのオートパイロット フレームワークです。 次の2つの要素で構成されています。 1. ゲーム中にロードされたSceneに応じて、対応するAgentを起動するディスパッチャ @@ -12,8 +14,6 @@ Unity製ゲームのオートパイロットツールです。 Agentとは、UI操作のプレイバックやモンキーテストなど、特定の操作を実行する小さく切り分けられたC#スクリプトです。 ビルトインで提供しているもののほか、ゲームタイトル固有のものを実装して使用できます。 -Click [English](./README.md) for English page if you need. - ## インストール方法 @@ -131,7 +131,7 @@ v1.0.0時点では `EmergencyExitAgent` の使用を想定しています。
handle Error
エラーを検知したらレポータで通知します
handle Assert
アサート違反を検知したらレポータで通知します
handle Warning
警告を検知したらレポータで通知します
-
Ignore Messages
ここに設定した文字列を含むメッセージはレポータで通知しません。正規表現でも指定できます
+
Ignore Messages
ここに設定した文字列を含むメッセージはレポータで通知しません。正規表現も使用可能で、エスケープはバックスラッシュ1文字（`\`）です
@@ -343,7 +343,7 @@ Automated QAによる操作のレコーディングは、Unityエディターの 1つの子Agentを登録し、それをAutopilot実行期間を通じて1回だけ実行できるAgentです。 2回目以降の実行はスキップされます。 -たとえば、タイトル画面で初回だけ導線が異なる、ホーム画面で初回だけログインボーナス受け取りがあるといったゲームにおいて、 通信エラーなどによるタイトル画面戻しが発生してもそのまま実行するシナリオを構築できます。 +たとえば、タイトル画面で初回だけ導線が異なる、ホーム画面で初回だけログインボーナス受け取りがあるといったゲームにおいて、 通信エラーなどによるタイトル画面戻しが発生してもそのまま実行するテストシナリオを構築できます。 このAgentのインスタンス（.assetファイル）には以下を設定できます。 @@ -356,7 +356,7 @@ Automated QAによる操作のレコーディングは、Unityエディターの 1つの子Agentを登録し、それを無限に繰り返し実行するAgentです。 -SerialCompositeAgentと組み合わせることで、シナリオを何周もしたり、シナリオの最後のAgentだけを繰り返し実行することができます。 +SerialCompositeAgentと組み合わせることで、一連の操作を何周もしたり、特定のAgentだけを繰り返し実行することができます。 なお、有限回の繰り返しはサポートしません（SerialCompositeAgentで実現できるため）。 このAgentのインスタンス（.assetファイル）には以下を設定できます。 @@ -385,7 +385,7 @@ SerialCompositeAgentと組み合わせることで、シナリオを何周もし ### EmergencyExitAgent -`DeNA.Anjin.Annotations` アセンブリに含まれる `EmergencyExit` コンポーネントの出現を監視し、表示されたら即クリックするAgentです。 +`DeNA.Anjin.Annotations` アセンブリに含まれる `EmergencyExitAnnotations` コンポーネントの出現を監視し、表示されたら即クリックするAgentです。 たとえば通信エラーや日またぎで「タイトル画面に戻る」ボタンのような、テストシナリオ遂行上イレギュラーとなる振る舞いが含まれるゲームで利用できます。 常に、他の（実際にゲーム操作を行なう）Agentと同時に起動しておく必要があります。 @@ -398,7 +398,7 @@ SerialCompositeAgentと組み合わせることで、シナリオを何周もし 以下のロガータイプが用意されています。これらをそのまま使用することも、ゲームタイトル固有のカスタムロガーを実装して使用することも可能です。 -### Composite Logger +### CompositeLogger 複数のロガーを登録し、そのすべてにログ出力を委譲するロガーです。 @@ -409,7 +409,7 @@ SerialCompositeAgentと組み合わせることで、シナリオを何周もし -### Console Logger +### ConsoleLogger ログをコンソールに出力するロガーです。 @@ -420,7 +420,7 @@ SerialCompositeAgentと組み合わせることで、シナリオを何周もし -### File Logger +### FileLogger ログを指定ファイルに出力するロガーです。 @@ -440,7 +440,7 @@ SerialCompositeAgentと組み合わせることで、シナリオを何周もし 以下のレポータタイプが用意されています。これらをそのまま使用することも、ゲームタイトル固有のカスタムレポータを実装して使用することも可能です。 -### Composite Reporter +### CompositeReporter 複数のレポータを登録し、そのすべてにレポート送信を委譲するレポータです。 @@ -451,19 +451,30 @@ SerialCompositeAgentと組み合わせることで、シナリオを何周もし -### Slack Reporter +### SlackReporter Slackにレポート送信するレポータです。 このレポータのインスタンス（.assetファイル）には以下を設定できます。
-
Slack Token
Slack通知に使用するWeb APIトークン（省略時は通知されない）。コマンドライン引数 -SLACK_TOKEN で上書きできます。
-
Slack Channels
Slack通知を送るチャンネル（省略時は通知されない）。カンマ区切りで複数指定できます。コマンドライン引数 -SLACK_CHANNELS で上書きできます。
-
Mention Sub Team IDs
Slack通知メッセージでメンションするチームのIDをカンマ区切りで指定します
-
Add Here In Slack Message
Slack通知メッセージに@hereを付けます。デフォルトはoff
+
Slack Token
通知に使用するSlack BotのOAuthトークン（省略時は通知されない）。 + コマンドライン引数 -SLACK_TOKEN で上書きできます。
+
Slack Channels
通知を送るチャンネル（省略時は通知されない）。カンマ区切りで複数指定できます。 + コマンドライン引数 -SLACK_CHANNELS で上書きできます。 + チャンネルにはBotを招待しておく必要があります。
+
Mention Sub Team IDs
通知メッセージでメンションするチームのIDをカンマ区切りで指定します
+
Add Here In Slack Message
通知メッセージに@hereを付けます。デフォルトはoff
+Botは次のページで作成できます。 +[Slack API: Applications](https://api.slack.com/apps) + +Botには次の権限が必要です。 + +- chat:write +- files:write + ## ゲームタイトル固有の実装 @@ -534,7 +545,7 @@ Anjinの操作を制御するためのアノテーションを定義していま このコンポーネントがアタッチされた`GameObject`は、`UGUIMonkeyAgent`によって操作されることを避けることができます。 -### EmergencyExit +### EmergencyExitAnnotations このコンポーネントがアタッチされた`Button`が表示されると、`EmergencyExitAgent`はすぐにクリックを試みます。 通信エラーや日またぎで「タイトル画面に戻る」ボタンのような、テストシナリオ遂行上イレギュラーとなるボタンに付けることを想定しています。 @@ -680,11 +691,23 @@ MIT License ## コントリビュート IssueやPull requestを歓迎します。 - Pull requestには `enhancement`, `bug`, `chore`, `documentation` といったラベルを付けてもらえるとありがたいです。 ブランチ名から自動的にラベルを付ける設定もあります。[PR Labeler settings](.github/pr-labeler.yml) を参照してください。 +おおまかな機能追加の受け入れ方針は次のとおりです。 + +- すべてのビルトイン機能は、Unityエディタのインスペクタウィンドウで設定を完結して使用できること +- `Autopilot` 本体への機能追加は極力避け、Agentなどによる拡張を検討する +- 汎用的でないAgentの追加は控える。ブログやGistでの公開、もしくはSamplesに置くことを検討する + + +次の機能要望およびPull requestは、Anjinのコンセプトに反するためリジェクトされます。 + +- 複数のテストシナリオ（AutopilotSettings）を連続実行する機能。Play Modeテストから実行する機能を利用してください +- AutopilotSettingsに「開始Scene」を指定できる機能。どのSceneからでも動作するテストシナリオを組むことを推奨しています + + ## 開発方法 本リポジトリをUnityプロジェクトのサブモジュールとして Packages/ ディレクトリ下に置いてください。