独自のBitriseプロジェクトスキャナーの作成

概要

A Bitrise project scanner must have a scan result model. Every platform scanner writes its possible options, configurations, and warnings into this model. These will be translated into Step input values by choosing the desired values for the given options.

プロジェクトスキャナーは、特定のプロジェクトのタイプを識別し、基本的なBitrise構成を生成するツールです。サポートされているプロジェクトタイプごとに独自のスキャナーがあります。これらのスキャナーは個別のパッケージとして保存されます。

プロジェクトタイプのスキャナーは、少なくとも2つのワークフローを定義します。1つはテスト用(primary)と構築用(deploy)。 それらを正常に実行するための最小限のステップが含まれています。

ステップの作成とテスト

ビルドステップとテストステップには、特定の要件があります。

  • ビルドステップでは、アプリをデプロイできるようにビルドし、出力ファイルを指す環境変数を出力する必要があります。たとえば、iOSアプリをビルドするためのビルドステップでは、.ipaファイル(たとえば、.xcodearchiveではない)とこの.ipaファイルへのパスを出力する必要があります。

  • テストステップは、bitrise.ioのビルドページで表示できるように、テスト結果を出力する必要があります。

ウェブサイトに新しいプロジェクトを追加したり、自分のマシンでプロジェクトを初期化したりする場合、 bitrise-init ツールはすべてのスキャナーを反復処理し、各スキャナーのスキャナーインターフェイスメソッドを呼び出して、それらの出力を収集します。これらの出力に基づいて、基本構成が生成されます。

可能なワークフローは、スキャン結果モデルで説明されています。モデルの構成は次のとおりです。

  • オプション

  • 構成

  • 警告

YAMLでのモデルの基本構造は次のとおりです。

options:
  DETECTED_PLATFORM_1: OptionModel
  DETECTED_PLATFORM_2: OptionModel
  ...

configs:
  DETECTED_PLATFORM_1:
    CONFIG_NAME_1: ConfigModel
    CONFIG_NAME_2: ConfigModel
    ...
  DETECTED_PLATFORM_2:
    CONFIG_NAME_1: ConfigModel
    CONFIG_NAME_2: ConfigModel
    ...
  ...

warnings:
  DETECTED_PLATFORM_1:
  - "warning message 1"
  - "warning message 2"
  ...
  DETECTED_PLATFORM_2:
  - "warning message 1"
  - "warning message 2"
  ...
  • すべてのプラットフォームスキャナーは、可能なオプション、構成、および警告をこのモデルに書き込みます。これらは、指定されたオプションに必要な値を選択することにより、ステップ入力値に変換されます。

  • すべてのオプションチェーンの最後のオプションが構成を選択します。

  • 警告は、特定のプロジェクト設定に関する問題を表示します。

オプション

Options 質問とその質問に対する可能な回答を表します。例えば:

  • 質問:iOSプロジェクトファイルへのパスは何ですか?

  • 考えられる回答:確認する可能性のあるパスのリスト

これらの質問と回答は、ステップ入力に変換されます。スキャナーは入力値を決定するか、ユーザーが値を選択または入力できるようにする必要があります。

たとえば、 Xcode Archive & Export for iOS ステップには、という入力があります export-method。これにより、エクスポートする.ipaのタイプがステップに通知されます。ソースコードに基づいて値を決定することはできないため、スキャナーはすべての可能な値を収集し、リストの形式でユーザーに提示して選択します。

オプションを選択すると、チェーンを開始できます。その後、さまざまなオプションが表示される可能性があります。たとえば、テストターゲットが関連付けられているXcodeスキームを選択すると、さまざまな「質問」が発生します。同様に、特定のオプションを選択すると、後で別のワークフローが生成される可能性があります。

オプションモデル

The OptionModel 入力オプションを表します。 Goでは次のようになります。

// OptionModel ...
type OptionModel struct {
    Title  string
    EnvKey string

    ChildOptionMap map[string]*OptionModel
    Config         string
}
  • Title:入力の人間が読める名前。

  • EnvKey:ステップモデルの入力のキーを表します。

  • ChildOptionMap:ユーザーがオプションに特定の値を選択した場合の後続のオプションのマップ。

たとえば、の値を選択するシナリオを見てみましょう。 Scheme 入力。あなたは value_map の中に options。可能な値は次のとおりです。

  • SchemeWithTest

  • SchemeWithoutTest

選択することにより SchemeWithTest、次のオプションは、テストの実行に使用されるシミュレーターに関連します。

選択することにより SchemeWithoutTest、次のオプションは、.ipaファイルのエクスポート方法に関するものです。

{
    "title": "Scheme",
    "env_key": "scheme",
    "value_map": {
        "SchemeWithTest": {
            "title": "Simulator name",
            "env_key": "simulator_name",
            ...
        },
        "SchemeWithoutTest": {
            "title": "Export method",
            "env_key": "export_method",
            ...
        }
    }
}

すべてのオプションチェーンには最初のオプションがあります:これは呼ばれます head。オプションの可能な値は、オプションチェーンを分岐させることができます。

すべてのオプションブランチの最後 options 持っている必要があります config プロパティセット。 config 生成されたBitrise構成のIDを保持します。

オプションチェーンの最後 options 持つことはできません value_map

{
    "title": "Scheme",
    "env_key": "scheme",
    "value_map": {
        "SchemeWithTest": {
            "title": "Simulator name",
            "env_key": "simulator_name",
            "value_map": {
                "-": {
                    "config": "bitrise_config_with_test",
                }
            }
        },
        "SchemeWithoutTest": {
            "title": "Export method",
            "env_key": "export_method",
            "value_map": {
                "development": {
                    "config": "bitrise_config_without_test",
                },
                "app-store": {
                    "config": "bitrise_config_without_test",
                },
                "ad-hoc": {
                    "config": "bitrise_config_without_test",
                }
            }
        }
    }
}

スキャナー

スキャナーは可能なものを生成します options チェーンと可能なワークフロー options プロジェクトタイプごと。 NS ActiveScanner 変数は、各スキャナーの実装を保持します。すべての特定のスキャナーは、 ScannerInterface

// ScannerInterface ...
type ScannerInterface interface {
    Name() string
    DetectPlatform(string) (bool, error)

    Options() (models.OptionModel, models.Warnings, error)
    Configs() (models.BitriseConfigMap, error)

    DefaultOptions() models.OptionModel
    DefaultConfigs() (models.BitriseConfigMap, error)

    ExcludedScannerNames() []string
}
  • Name() string:このメソッドは、スキャナー出力(警告、オプション、および構成)のログ記録と保存に使用されます。スキャナー出力はに保存されます map[SCANNER_NAME]OUTPUT。たとえば、 options iOSプロジェクトの場合はに保存されます optionsMap[ios]options

  • DetectPlatform(string) (bool, error):このメソッドは、指定された検索ディレクトリにプロジェクトタイプが含まれているかどうかを判断するために使用されます。

  • Options() (models.OptionModel, models.Warnings, error):このメソッドは、プロジェクトのオプションブランチを生成するために使用されます。各ブランチは、最終的なビットライズ構成モデルを構築するための完全で有効なオプションセットを定義する必要があります。すべてのオプションブランチの最後 Options 構成IDを保存する必要があります。これには、選択したオプションが入力されます。

  • Configs() (models.BitriseConfigMap, error):このメソッドは、可能な構成を生成するために使用されます。 BitriseConfigMapの各要素は、ユーザーが選択したオプション値で満たされるビットライズ構成テンプレートです。

  • DefaultOptions() models.OptionModel and DefaultConfigs() (models.BitriseConfigMap, error) :これらのメソッドは、特定のプロジェクトをスキャンせずにオプションと構成を生成するために使用されます。この場合、必要なすべてのステップ入力値はユーザーによって提供されます。このようにして、スキャナーに障害が発生した場合でも、ユーザーは開始するオプションがあります。

スキャナーのテスト

スキャナーをテストするには、単体テストと統合テストの両方が必要です。

ユニットテストは、Goの標準テストライブラリを使用して記述されています。

統合テストでは、プロジェクトタイプのスキャナーがプロジェクトタイプのインスタンスに必要なビットライズ構成を生成していることを検証しています。これを行うには、新しいスキャナーを使用して特定のサンプルプロジェクトをスキャンし、生成されたスキャン結果を統合テストに合うように変更します。

変更の理由は、スキャナーが生成された構成にステップを追加しているが、ステップのバージョンは時々更新されるためです。ステップバージョンの定義は、次の場所にあります。 steps/const.go

だから私たちは bitrise-init --ci config サンプルプロジェクトのルートディレクトリ、および生成された scan_result.yml ステップバージョンを置き換えるファイル %s 使用します fmt.Sprintf 最新の定義済みステップバージョンを構成に挿入します。

統合テストでは、 scan_result.yml 以前に生成された参照を使用してスキャナーによって生成されたファイル scan_result コンテンツ。

独自のスキャナーを提出する

独自のスキャナーをBitriseに送信できます。承認されたら、スキャナーを確認してbitrise-initツールに統合します。

新しいスキャナーの開発パスは、独自のサンプルプロジェクトで始まり、プロジェクトタイプの既存のステップを更新することで終わります。やってみよう!

  1. プロジェクトタイプの典型的なインスタンスを示すオープンソースのサンプルアプリを検索または作成します。

    以下を含める必要があります。

    • readmeファイル(このプロジェクトの更新、ビルド、およびテストに必要なツールバージョンを含む)。

    • a bitrise.yml スキャナーによって生成されたファイル。

  2. 既存のステップまたはカスタムスクリプトを使用してサンプルアプリをビルドおよびテストします。

  3. 新しいプロジェクトタイプに必要な不足しているステップを作成します。

    これらのステップのPRは、スキャナーを作成した後、スキャナーのPRをリンクする必要があります。

  4. プロジェクトタイプのスキャナーを作成します。

  5. 必要な単体テストと統合テストを実行します。

  6. bitrise-initプロジェクトへのスキャナープルリクエストを開きます。

    そうすべき:

    • 新しいプロジェクトタイプのサンプルアプリをリンクします。

    • テストと構築のための新しいプロジェクトタイプのガイドをリンクします。

    • 新しいプロジェクトタイプのアイコンを含めます。そうでない場合は、アイコンを作成します。

    • 新しいプロジェクトタイプを構築およびテストするために必要なツールをリストして、デフォルトのスタックを推奨します。

  7. 必要に応じて、既存のステップを新しいプロジェクトタイプで更新します。

    これらのステップのPRは、スキャナーのPRをリンクする必要があります。