Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Mod README, add a general policy for accepting/rejecting new features. #83

Open
wants to merge 2 commits into
base: master
Choose a base branch
from
Open

Mod README, add a general policy for accepting/rejecting new features. #83

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
88e0b24
Fix wording
nowsprinting Oct 22, 2024
ab0481a
Add a general policy for accepting/rejecting new features
nowsprinting Oct 22, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
59 changes: 40 additions & 19 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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&registry_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
Expand All @@ -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 those provided built-in, game title-specific ones can be implemented and used.

Click [日本語](./README_ja.md) for the Japanese page if you need.



## Installation
Expand Down Expand Up @@ -134,7 +134,7 @@ Set up a filter to catch abnormal log messages and notify using Reporter.
<dt>Handle Error</dt><dd>Report when error message is detected in log</dd>
<dt>Handle Assert</dt><dd>Report when assert message is detected in log</dd>
<dt>Handle Warning</dt><dd>Report when warning message is detected in log</dd>
<dt>Ignore Messages</dt><dd>Log messages containing this string will not be reported. Regex is also available.</dd>
<dt>Ignore Messages</dt><dd>Log messages containing this string will not be reported. Regex is also available, and escape is a single backslash (`\`).</dd>
</dl>


Expand Down Expand Up @@ -332,7 +332,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.

Expand All @@ -345,7 +345,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.
Expand Down Expand Up @@ -374,7 +374,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).
Expand All @@ -387,7 +387,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 project-specific Loggers can be implemented and used.


### Composite Logger
### CompositeLogger

A Logger that delegates to multiple loggers.

Expand All @@ -398,7 +398,7 @@ The instance of this Logger (.asset file) can have the following settings.
</dl>


### Console Logger
### ConsoleLogger

A Logger that outputs to a console.

Expand All @@ -409,7 +409,7 @@ The instance of this Logger (.asset file) can have the following settings.
</dl>


### File Logger
### FileLogger

A Logger that outputs to a specified file.

Expand All @@ -429,7 +429,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 project-specific Reporters can be implemented and used.


### Composite Reporter
### CompositeReporter

A Reporter that delegates to multiple Reporters.

Expand All @@ -440,21 +440,30 @@ The instance of this Reporter (.asset file) can have the following settings.
</dl>


### Slack Reporter
### SlackReporter

A Reporter that post report to Slack.

The instance of this Reporter (.asset file) can have the following settings.

<dl>
<dt>Slack Token</dt><dd>Web API token used for Slack notifications. If omitted, no notifications will be sent.
<dt>Slack Token</dt><dd>Oath token of Slack Bot used for notifications. If omitted, no notifications will be sent.
This setting can be overwritten with the command line argument <code>-SLACK_TOKEN</code>.</dd>
<dt>Slack Channels</dt><dd>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 <code>-SLACK_CHANNELS</code>.</dd>
<dt>Mention Sub Team IDs</dt><dd>Comma Separated Team IDs to Mention in Slack Notification Message</dd>
<dt>Add Here In Slack Message</dt><dd>Add @here to Slack notification message. Default is off</dd>
<dt>Slack Channels</dt><dd>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 <code>-SLACK_CHANNELS</code>.
The bot must be invited to the channel.</dd>
<dt>Mention Sub Team IDs</dt><dd>Comma Separated Team IDs to mention in notification message</dd>
<dt>Add Here In Slack Message</dt><dd>Add @here to notification message. Default is off</dd>
</dl>

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 code
Expand Down Expand Up @@ -524,7 +533,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.
Expand Down Expand Up @@ -585,10 +594,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.
Expand Down
59 changes: 41 additions & 18 deletions README_ja.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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&registry_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を起動するディスパッチャ
Expand All @@ -12,8 +14,6 @@ Unity製ゲームのオートパイロットツールです。
Agentとは、UI操作のプレイバックやモンキーテストなど、特定の操作を実行する小さく切り分けられたC#スクリプトです。
ビルトインで提供しているもののほか、ゲームタイトル固有のものを実装して使用できます。

Click [English](./README.md) for English page if you need.



## インストール方法
Expand Down Expand Up @@ -131,7 +131,7 @@ v1.0.0時点では `EmergencyExitAgent` の使用を想定しています。
<dt>handle Error</dt><dd>エラーを検知したらレポータで通知します</dd>
<dt>handle Assert</dt><dd>アサート違反を検知したらレポータで通知します</dd>
<dt>handle Warning</dt><dd>警告を検知したらレポータで通知します</dd>
<dt>Ignore Messages</dt><dd>ここに設定した文字列を含むメッセージはレポータで通知しません。正規表現でも指定できます</dd>
<dt>Ignore Messages</dt><dd>ここに設定した文字列を含むメッセージはレポータで通知しません。正規表現も使用可能で、エスケープはバックスラッシュ1文字（`\`）です</dd>
</dl>


Expand Down Expand Up @@ -336,7 +336,7 @@ Automated QAによる操作のレコーディングは、Unityエディターの
1つの子Agentを登録し、それをAutopilot実行期間を通じて1回だけ実行できるAgentです。
2回目以降の実行はスキップされます。

たとえば、タイトル画面で初回だけ導線が異なる、ホーム画面で初回だけログインボーナス受け取りがあるといったゲームにおいて、 通信エラーなどによるタイトル画面戻しが発生してもそのまま実行するシナリオを構築できます。
たとえば、タイトル画面で初回だけ導線が異なる、ホーム画面で初回だけログインボーナス受け取りがあるといったゲームにおいて、 通信エラーなどによるタイトル画面戻しが発生してもそのまま実行するテストシナリオを構築できます。

このAgentのインスタンス（.assetファイル）には以下を設定できます。

Expand All @@ -349,7 +349,7 @@ Automated QAによる操作のレコーディングは、Unityエディターの

1つの子Agentを登録し、それを無限に繰り返し実行するAgentです。

SerialCompositeAgentと組み合わせることで、シナリオを何周もしたり、シナリオの最後のAgentだけを繰り返し実行することができます。
SerialCompositeAgentと組み合わせることで、一連の操作を何周もしたり、特定のAgentだけを繰り返し実行することができます。
なお、有限回の繰り返しはサポートしません（SerialCompositeAgentで実現できるため）。

このAgentのインスタンス（.assetファイル）には以下を設定できます。
Expand Down Expand Up @@ -378,7 +378,7 @@ SerialCompositeAgentと組み合わせることで、シナリオを何周もし

### EmergencyExitAgent

`DeNA.Anjin.Annotations` アセンブリに含まれる `EmergencyExit` コンポーネントの出現を監視し、表示されたら即クリックするAgentです。
`DeNA.Anjin.Annotations` アセンブリに含まれる `EmergencyExitAnnotations` コンポーネントの出現を監視し、表示されたら即クリックするAgentです。
たとえば通信エラーや日またぎで「タイトル画面に戻る」ボタンのような、テストシナリオ遂行上イレギュラーとなる振る舞いが含まれるゲームで利用できます。

常に、他の（実際にゲーム操作を行なう）Agentと同時に起動しておく必要があります。
Expand All @@ -391,7 +391,7 @@ SerialCompositeAgentと組み合わせることで、シナリオを何周もし
以下のロガータイプが用意されています。これらをそのまま使用することも、プロジェクト独自のロガーを実装して使用することも可能です。


### Composite Logger
### CompositeLogger

複数のロガーを登録し、そのすべてにログ出力を委譲するロガーです。

Expand All @@ -402,7 +402,7 @@ SerialCompositeAgentと組み合わせることで、シナリオを何周もし
</dl>


### Console Logger
### ConsoleLogger

ログをコンソールに出力するロガーです。

Expand All @@ -413,7 +413,7 @@ SerialCompositeAgentと組み合わせることで、シナリオを何周もし
</dl>


### File Logger
### FileLogger

ログを指定ファイルに出力するロガーです。

Expand All @@ -433,7 +433,7 @@ SerialCompositeAgentと組み合わせることで、シナリオを何周もし
以下のレポータタイプが用意されています。これらをそのまま使用することも、プロジェクト独自のレポータを実装して使用することも可能です。


### Composite Reporter
### CompositeReporter

複数のレポータを登録し、そのすべてにレポート送信を委譲するレポータです。

Expand All @@ -444,19 +444,30 @@ SerialCompositeAgentと組み合わせることで、シナリオを何周もし
</dl>


### Slack Reporter
### SlackReporter

Slackにレポート送信するレポータです。

このレポータのインスタンス（.assetファイル）には以下を設定できます。

<dl>
<dt>Slack Token</dt><dd>Slack通知に使用するWeb APIトークン（省略時は通知されない）。コマンドライン引数 <code>-SLACK_TOKEN</code> で上書きできます。</dd>
<dt>Slack Channels</dt><dd>Slack通知を送るチャンネル（省略時は通知されない）。カンマ区切りで複数指定できます。コマンドライン引数 <code>-SLACK_CHANNELS</code> で上書きできます。</dd>
<dt>Mention Sub Team IDs</dt><dd>Slack通知メッセージでメンションするチームのIDをカンマ区切りで指定します</dd>
<dt>Add Here In Slack Message</dt><dd>Slack通知メッセージに@hereを付けます。デフォルトはoff</dd>
<dt>Slack Token</dt><dd>通知に使用するSlack BotのOAuthトークン（省略時は通知されない）。
コマンドライン引数 <code>-SLACK_TOKEN</code> で上書きできます。</dd>
<dt>Slack Channels</dt><dd>通知を送るチャンネル（省略時は通知されない）。カンマ区切りで複数指定できます。
コマンドライン引数 <code>-SLACK_CHANNELS</code> で上書きできます。
チャンネルにはBotを招待しておく必要があります。</dd>
<dt>Mention Sub Team IDs</dt><dd>通知メッセージでメンションするチームのIDをカンマ区切りで指定します</dd>
<dt>Add Here In Slack Message</dt><dd>通知メッセージに@hereを付けます。デフォルトはoff</dd>
</dl>

Botは次のページで作成できます。
[Slack API: Applications](https://api.slack.com/apps)

Botには次の権限が必要です。

- chat:write
- files:write



## ゲームタイトル独自処理の実装
Expand Down Expand Up @@ -527,7 +538,7 @@ Anjinの操作を制御するためのアノテーションを定義していま
このコンポーネントがアタッチされた`GameObject`は、`UGUIMonkeyAgent`によって操作されることを避けることができます。


### EmergencyExit
### EmergencyExitAnnotations

このコンポーネントがアタッチされた`Button`が表示されると、`EmergencyExitAgent`はすぐにクリックを試みます。
通信エラーや日またぎで「タイトル画面に戻る」ボタンのような、テストシナリオ遂行上イレギュラーとなるボタンに付けることを想定しています。
Expand Down Expand Up @@ -588,11 +599,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/ ディレクトリ下に置いてください。
Expand Down