# RSpec リファレンス

あなたのコネクターが日々のビジネスシナリオやユーザーシナリオをサポートできるか検証するテストを設計し、ビジネス利用におけるシステムの適格性と正確性を確認しましょう。

# RSpec の基本的なセットアップ

どのような RSpec テストも、簡単にまとめると以下のような手順で進められます。

  1. コネクターインスタンスを作成
  2. 設定インスタンスを作成
  3. コネクターインスタンスと設定インスタンスを利用して、関連する RSpec コマンドを実行
RSpec.describe 'methods/user_tenants', :vcr do
  let(:connector) { Workato::Connector::Sdk::Connector.from_file('connector.rb', settings) }
  let(:settings) { Workato::Connector::Sdk::Settings.from_default_file }

  subject(:result) { connector.methods.user_tenants(arg_1) }

  context 'when invoked' do
    ... # RSpec tests
  end
end

まずは、Gem を使用してコネクターのインスタンスを作成する必要があります。その後、このコネクターのインスタンスは、さらにコマンドを呼び出してコネクター内の lambda 関数を実行するために使用されます。これは、上記のサンプルでは let(:connector) ... の部分に相当します。

次に、コネクションのインスタンスを作成する必要もあります。これは、Workato 上での実際のコネクションのようなものであると考えてください。コネクターのインスタンスと設定のインスタンスの両方が連係することで、RSpec の実行時に有効な HTTP リクエストを送信できるようになります。これは、上記のサンプルでは let(:settings) ... の部分に相当します。

さらにその後、context 属性内で RSpec コマンドを指定します。

# コネクターインスタンスの作成

# from_file

RSpec テストで使用できるコネクターインスタンスを作成します。これは、あらゆる RSpec テストの基本的な構成要素となります。

属性 説明
用途 コネクターインスタンスを作成
入力 path_to_file - テストにおけるコネクターのパス。

settings - 設定ファイルのパス。設定ファイルを事前に読み込んでコネクターインスタンスを作成するために使用されます。これはインポートです
出力 使用可能なコネクターインスタンス
使用方法 Workato::Connector::Sdk::Connector.from_file('connector.rb', settings)

# 設定インスタンスの作成

設定インスタンスの作成方法は3通りあります。

  1. デフォルトファイルから作成
  2. 指定されたファイルから作成
  3. 暗号化ファイルから作成

# from_default_file

RSpec テストで使用される設定インスタンスを作成したいときには、ほとんどの場合、これを使用します。これも、あらゆる RSpec テストの基本的な構成要素となります。暗号化ファイルと暗号化されていないファイルのどちらに対しても使用できます。

名前付きのコネクションは使用しない

設定ファイルに名前付きのコネクションを含めることはできません。つまり、資格情報は1セットに限られている必要があるということです。 たとえば、次の記述は適切です。

api_key: valid_api_key
domain: valid_domain

次の記述は不適切です。

My Valid Connection:
   api_key: valid_api_key
   domain: valid_domain
My invalid Connection:
   api_key: invalid_api_key
   domain: valid_domain
属性 説明
用途 コネクターインスタンスとともに使用される設定インスタンスを作成。
入力 N/A
出力 使用可能な設定インスタンス
使用方法 Workato::Connector::Sdk::Settings.from_default_file

TIP

これを使用する場合、呼び出し元のルートディレクトリにおいて最初に settings.yaml.enc ファイルと master.key ファイルが探されます。settings.yaml.enc ファイルが見つからなければ、続いてデフォルトでは setting.yaml ファイルが使用されます。

# from_file

RSpec テストで使用できる設定インスタンスを作成します。これも、あらゆる rSpec テストの基本的な構成要素となります。

この方法は暗号化されていない settings.yaml ファイルに使用してください。

属性 説明
用途 コネクターインスタンスとともに使用される設定インスタンスを作成。 暗号化されていない settings.yaml ファイルに使用してください。
入力 path - 設定ファイルのパス。

name - settings.yaml ファイル内に複数のコネクションがある場合のコネクション名
出力 使用可能な設定インスタンス
使用方法 Workato::Connector::Sdk::Settings.from_file('settings.yaml')

# from_encrypted_file

RSpec テストで使用できる設定インスタンスを作成します。これも、あらゆる RSpec テストの基本的な構成要素となります。

この方法は暗号化された settings.yaml.enc ファイルに使用してください。

属性 説明
用途 コネクターインスタンスとともに使用される設定インスタンスを作成。 暗号化された settings.yaml.enc ファイルに使用してください。
入力 path - 設定ファイルのパス。

name - settings.yaml ファイルに複数のコネクションがある場合のコネクション名

key - settings.yaml.enc ファイルの復号に使用される master.key のパス。
出力 使用可能な設定インスタンス
使用方法 Workato::Connector::Sdk::Settings.from_encrypted_file('settings.yaml.enc', 'master.key')

# test の lambda 関数のテスト

connector_spec.rb 内の test の lambda 関数をトリガーするには、connector.test(settings) を使用します。

CLI コマンド workato generate test を使用すると、spec フォルダーにスタブを自動生成できます。

属性 説明
用途 コネクター内の test の lambda 関数を呼び出す。
入力 settings - 設定インスタンス
出力 test の lambda 関数の出力
使用方法 connector.test(settings)

# 例: RSpec テスト - test の lambda 関数のテスト

RSpec.describe 'connector', :vcr do
  let(:connector) { Workato::Connector::Sdk::Connector.from_file('connector.rb', settings) }
  let(:settings) { Workato::Connector::Sdk::Settings.from_default_file }

  it { expect(connector).to be_present }

  describe 'test' do
    # Assign the output variable as the output of your test lambda
    subject(:output) { connector.test(settings) } 

    context 'given valid credentials' do
      it 'establishes valid connection' do
        expect(output).to be_truthy
      end

      it 'returns response that is not excessively large' do
        # large Test responses might also cause connections to be evaluated wrongly
        expect(output.to_s.length).to be < 5000
      end
    end

    context 'given invalid credentials' do
      let(:settings) { Workato::Connector::Sdk::Settings.from_encrypted_file('invalid_settings.yaml.enc') }

      it 'establishes invalid connection' do
        expect { output }
          .to raise_error('500 Internal Server Error')
      end
    end
  end
end

# アクションのテスト

RSpec の基本的なセットアップ」が済んだら、コネクター内のさまざまな lambda 関数を呼び出せます。これは、コネクターインスタンス上でインスタンスメソッドを呼び出すことで実行できます。

CLI コマンド workato generate test を使用すると、spec フォルダーにスタブを自動生成できます。各アクションには、それぞれに固有の spec ファイルが用意されます。

# アクション全体のテスト

スキーマを含めてアクション全体をテストするには、subject(:output) { connector.actions.[action_name](input) } を参照して、そのアクションを RSpec テストの対象にするだけです。

属性 説明
用途 関連するスキーマ変換やトグル項目を含めて、特定のコネクターのアクション全体を呼び出す。
入力 input - レシピエディターからアクションに直接渡される入力 JSON データの JSON 表現。
出力 アクションの出力
使用方法 connector.actions.[action_name](input) または connector.actions.[action_name].invoke(input)

# 例: RSpec テスト - アクション全体のテスト

RSpec.describe "actions/search_customers", :vcr do

  # Spec describes the most commons blocks of an action. Remove describes that you don"t need.
  # Ref: https://docs.workato.com/developing-connectors/sdk/cli/guides/cli/actions.html for test examples

  subject(:output) { connector.actions.search_customers(input) }

  let(:connector) { Workato::Connector::Sdk::Connector.from_file("connector.rb") }
  let(:settings) { Workato::Connector::Sdk::Settings.from_default_file }
  let(:input) { JSON.parse(File.read('fixtures/actions/search_customers/input.json')) }

  let(:expected_output) { JSON.parse(File.read('fixtures/actions/search_customers/output.json')) }

  describe 'Run entire action with valid input' do
    it 'gives expected output' do
      expect(output).to eq(expected_output)
    end
  end
end

# execute の lambda 関数のテスト

コネクターインスタンス内の特定のアクションをトリガーするには、execute(**args) を使用します。

属性 説明
用途 特定コネクター内の execute の lambda 関数を呼び出す
入力 settings - 設定インスタンス

input - execute の lambda 関数に提供される入力引数の JSON 表現。

extended_input_schema - execute の lambda 関数に提供される拡張入力スキーマ引数の JSON 表現。

extended_output_schema - execute の lambda 関数に提供される拡張出力スキーマ引数の JSON 表現。

注意: これらの引数が必要とされない場合、それを定義する必要はありません。
出力 execute の lambda 関数の出力
使用方法 connector.actions.[action_name].execute(settings, input, extended_input_schema, extended_output_schema)

# 例: RSpec テスト - execute の lambda 関数のテスト

RSpec.describe "actions/search_customers", :vcr do

  # Spec describes the most commons blocks of an action. Remove describes that you don"t need.
  # Ref: https://docs.workato.com/developing-connectors/sdk/unit-testing.html#action for test examples

  let(:connector) { Workato::Connector::Sdk::Connector.from_file("connector.rb") }
  let(:settings) { Workato::Connector::Sdk::Settings.from_default_file }

  let(:action) { connector.actions.search_customers }

  describe "execute" do
    subject(:output) { action.execute(settings, input) }
    let(:input) { JSON.parse(File.read('input/search_customer_input.json')) }
    let(:expected_output) { JSON.parse(File.read('output/search_customer_output.json')) }

    context 'given valid input' do
      it 'gives expected output' do
        expect(output).to eq(expected_output)
      end
    end
  end
end

# input_fields の lambda 関数のテスト

コネクターインスタンス内の特定のアクションに含まれる input_fields の lambda 関数を呼び出すには、input_fields(**args) を使用します。

属性 説明
用途 特定コネクターの input_fields の lambda 関数を呼び出す
入力 settings - 設定インスタンス

config_fields - config_fields の lambda 関数から渡されるコンフィギュレーション項目値の JSON 表現。

注意: これらの引数が必要とされない場合、それを定義する必要はありません。
出力 input_fields の lambda 関数の出力
使用方法 connector.actions.[action_name].input_fields(settings, config_fields)

TIP

input_fields の lambda 関数には object_definitions が存在しているため、それがどこに指定されているのか不思議に思うかもしれません。引数 object_definitions を明示的に渡す必要はありません。それはすでにコネクターインスタンスから暗黙的に渡されているためです。

# output_fields の lambda 関数のテスト

コネクターインスタンス内の特定のアクションに含まれる output_fields の lambda 関数を呼び出すには、output_fields(**args) を使用します。

属性 説明
用途 特定コネクターの output_fields の lambda 関数を呼び出す
入力 settings - 設定インスタンス

config_fields - config_fields の lambda 関数から渡されるコンフィギュレーション項目値の JSON 表現。

注意: これらの引数が必要とされない場合、それを定義する必要はありません。
出力 output_fields の lambda 関数の出力
使用方法 connector.actions.[action_name].output_fields(settings, config_fields)

TIP

input_fields の lambda 関数には object_definitions が存在しているため、それがどこに指定されているのか不思議に思うかもしれません。引数 object_definitions を明示的に渡す必要はありません。それはすでにコネクターインスタンスから暗黙的に渡されているためです。

# sample_output の lambda 関数のテスト

コネクターインスタンス内の特定のアクションに含まれる sample_output の lambda 関数を呼び出すには、sample_output(**args) を使用します。

属性 説明
用途 特定コネクター内の sample_output の lambda 関数を呼び出す
入力 settings - 設定インスタンス

input - execute の lambda 関数に提供される入力引数の JSON 表現。

注意: これらの引数が必要とされない場合、それを定義する必要はありません。
出力 sample_output の lambda 関数の出力
使用方法 connector.actions.[action_name].sample_output(settings, input)

# そのほかに利用可能なアクションインスタンスのメソッド

  • summarize_input(**args)
  • summarize_output(**args)

# トリガーのテスト

RSpec の基本的なセットアップ」が済んだら、コネクター内のさまざまな lambda 関数を呼び出せます。これは、コネクターインスタンス上でインスタンスメソッドを呼び出すことで実行できます。

CLI コマンド workato generate test を使用すると、spec フォルダーにスタブを自動生成できます。各トリガーには、それぞれに固有の spec ファイルが用意されます。

各トリガーのスタブには、Webhook トリガーとポーリングトリガーの両方について考えられる限りのあらゆる lambda 関数が用意されます。それらは必要に応じて削除する必要があります。

# トリガー全体のテスト

スキーマを含めてトリガー全体をテストするには、subject(:output) { connector.triggers.[trigger_name](input) } を参照して、そのアクションを RSpec テストの対象にするだけです。

属性 説明
用途 関連するスキーマ変換やトグル項目を含めて、特定のコネクターのトリガーポーリング全体を呼び出す。
入力 input - レシピエディターからアクションに直接渡される入力 JSON データの JSON 表現。
出力 スキーマ変換を含むトリガーの出力
使用方法 connector.triggers.[trigger_name](input) または connector.triggers.[trigger_name].invoke(input)

# 例: RSpec テスト - トリガー全体のテスト

RSpec.describe "triggers/new_updated_object", :vcr do

  # Spec describes the most commons blocks of a trigger.
  # Depending on the type of your trigger remove describes that you don't need.
  # Learn more: https://docs.workato.com/developing-connectors/sdk/cli/reference/rspec-commands.html

  subject(:output) { connector.triggers.new_updated_object(input) }

  let(:connector) { Workato::Connector::Sdk::Connector.from_file("connector.rb") }
  let(:settings) { Workato::Connector::Sdk::Settings.from_default_file }
  let(:input) { JSON.parse(File.read('fixtures/triggers/new_updated_object/input.json')) }

  let(:expected_output) { JSON.parse(File.read('fixtures/triggers/new_updated_object/output.json')) }

  describe 'Run entire trigger with valid input' do
    it 'gives expected output' do
      expect(output).to eq(expected_output)
    end
  end
end

# poll の lambda 関数のテスト

コネクターインスタンス内の特定のトリガーに含まれる poll の lambda 関数を呼び出すには、poll(**args) を使用します。これにより、特定期間内のイベントすべてのページネーションされたレコードが取得されます。その期間は、since 入力で指定されたものとなります。詳細については、「ページネーションされた poll の lambda 関数」の例を参照してください。

属性 説明
用途 コネクターに含まれる特定トリガーの poll の lambda 関数を呼び出し、ページネーションを行う
入力 settings - 設定インスタンス

input - execute の lambda 関数に提供される入力引数の JSON 表現。

closure - poll の lambda 関数の以前の呼び出しから渡されるクロージャの JSON 表現。

注意: これらの引数が必要とされない場合、それを定義する必要はありません。
出力 poll の lambda 関数の出力
使用方法 connector.triggers.[trigger_name].poll(settings, input, closure)

動作の仕組み

このインスタンスメソッドは、Workato のプラットフォーム上のポーリング機構をシミュレートします。その対象には、 can_poll_more 属性が true の場合に発生する可能性のあるページネーションも含まれます。 これは、複数のポーリングから単一の出力にまとめられます。例: 初回のポーリングが次のような出力であるとします。

{
  events: [
    { 'id' => 2, 'title' => 'Post #2' },
    { 'id' => 1, 'title' => 'Post #1' }
  ],
  next_poll: 2,
  can_poll_more: true
}

そして、2回目のポーリングが次のような出力であるとします。

{
  events: [
    { 'id' => 4, 'title' => 'Post #4' },
    { 'id' => 3, 'title' => 'Post #3' },
  ],
  next_poll: 4,
  can_poll_more: false
}

その場合、このメソッドの最終的な出力は以下のようになります。

{
  events: [
    { 'id' => 4, 'title' => 'Post #4' },
    { 'id' => 3, 'title' => 'Post #3' },
    { 'id' => 2, 'title' => 'Post #2' },
    { 'id' => 1, 'title' => 'Post #1' }
  ],
  next_poll: 4,
  can_poll_more: false
}

# poll_page の lambda 関数のテスト

コネクターインスタンス内の特定のトリガーに含まれる poll_page の lambda 関数を呼び出すには、poll_page(**args) を使用します。このメソッドでは、イベントが複数ある場合でも、単一のページしか取得されません。

属性 説明
用途 コネクターに含まれる特定トリガーの poll の lambda 関数を呼び出し、ページネーションは行わない
入力 settings - 設定インスタンス

input - execute の lambda 関数に提供される入力引数の JSON 表現。

closure - poll の lambda 関数の以前の呼び出しから渡されるクロージャの JSON 表現。

注意: これらの引数が必要とされない場合、それを定義する必要はありません。
出力 poll の lambda 関数の出力
使用方法 connector.triggers.[trigger_name].poll_page(settings, input, closure)

TIP

このインスタンスメソッドは、与えられたクロージャでの 単一の ポーリングをシミュレートしています。複数回のポーリングは行いません。

# webhook_subscribe の lambda 関数のテスト

コネクターインスタンス内の特定のトリガーに含まれる webhook_subscribe の lambda 関数を呼び出すには、webhook_subscribe(**args) を使用します。

属性 説明
用途 コネクター内の特定トリガーの webhook_subscribe の lambda 関数を呼び出す
入力 webhook_url - 引数として渡される Webhook の URL。request.bin の URL を使用してスタブにすることも可能。

settings - 設定インスタンス

input - webhook_subscribe の lambda 関数に提供される入力引数の JSON 表現。

recipe_id - シミュレートされるレシピの ID。指定されない場合は、デフォルトで UUID が使用される。
出力 webhook_subscribe の lambda 関数の出力
使用方法 connector.triggers.[trigger_name].webhook_subscribe(webhook_url, settings)

# webhook_unsubscribe の lambda 関数のテスト

コネクターインスタンス内の特定のトリガーに含まれる webhook_unsubscribe の lambda 関数を呼び出すには、webhook_unsubscribe(**args) を使用します。

属性 説明
用途 コネクターに含まれる特定トリガーの webhook_unsubscribe の lambda 関数を呼び出す
入力 subscribe_output - webhook_subscribe の lambda 関数の出力の JSON 表現。
出力 webhook_unsubscribe の lambda 関数の出力
使用方法 connector.triggers.[trigger_name].webhook_unsubscribe(subscribe_output)

# webhook_notification の lambda 関数のテスト

コネクターインスタンス内の特定のトリガーに含まれる webhook_notification の lambda 関数を呼び出すには、webhook_notification(**args) を使用します。

属性 説明
用途 コネクターに含まれる特定トリガーの webhook_notification の lambda 関数を呼び出す
入力 input - webhook_subscribe の lambda 関数に提供される入力引数の JSON 表現。

payload - Webhook のペイロード。テストを行うには、想定される Webhook のペイロードを渡す必要があります。

extended_input_schema - execute の lambda 関数に提供される拡張入力スキーマ引数の JSON 表現。

extended_output_schema - execute の lambda 関数に提供される拡張出力スキーマ引数の JSON 表現。

header - Webhook のヘッダー。

params - Webhook のクエリーパラメータ。

注意: これらの引数が必要とされない場合、それを定義する必要はありません。
出力 webhook_notification の lambda 関数の出力
使用方法 connector.triggers.[trigger_name].webhook_notification(input, payload, extended_input_schema, extended_output_schema, header, params)

# そのほかに利用可能なトリガーインスタンスのメソッド


# method の lambda 関数のテスト

connector_spec.rb 内の method の lambda 関数をトリガーするには、connector.methods.<method_name>(**args) を使用します。

RSpec の基本的なセットアップ」が済んだら、コネクター内のさまざまな lambda 関数を呼び出せます。これは、コネクターインスタンス上でインスタンスメソッドを呼び出すことで実行できます。

CLI コマンド workato generate test を使用すると、spec フォルダーにスタブを自動生成できます。各メソッドには、それぞれに固有の spec ファイルが用意されます。

属性 説明
用途 コネクター内の特定の method の lambda 関数を呼び出す。
入力 設定可能。メソッドによる
出力 method の lambda 関数の出力
使用方法 connector.methods.<method_name>(**args)

# 例: RSpec テスト - method の lambda 関数のテスト

# frozen_string_literal: true

RSpec.describe "methods/make_schema_builder_fields_sticky", :vcr do
  let(:connector) { Workato::Connector::Sdk::Connector.from_file("connector.rb", settings) }
  let(:settings) { Workato::Connector::Sdk::Settings.from_default_file }

  subject(:result) { connector.methods.make_schema_builder_fields_sticky(schema) }

  context "given non-sticky schema" do
    let(:schema) { JSON.parse(File.read('fixtures/methods/make_schema_builder_fields_sticky/make_schema_builder_fields_sticky_input.json')) }
    let(:expected_output) { JSON.parse(File.read('fixtures/methods/make_schema_builder_fields_sticky/make_schema_builder_fields_sticky_output.json')) }
    it "makes all fields sticky" do 
      expect(result).to eq(expected_output)
    end
  end
end

# object_definitions の lambda 関数のテスト

connector_spec.rb 内の object_definitions の lambda 関数をトリガーするには、[object_definition_name].fields(**args) を使用します。

CLI コマンド workato generate test を使用すると、spec フォルダーにスタブを自動生成できます。それぞれの object_definitions の lambda 関数には、各々に固有の spec ファイルが用意されます。

属性 説明
用途 コネクターに含まれる特定の object_definitions の lambda 関数を呼び出す。
入力 settings - 設定インスタンス

config_fields - config_fields の JSON 表現。
出力 object_definitions の lambda 関数の出力
使用方法 connector.object_definitions.[object_definition_name].fields(settings, config_fields)

# 例: RSpec テスト - object_definition の lambda 関数のテスト

# frozen_string_literal: true

RSpec.describe "object_definition/compound_type", :vcr do
  let(:connector) { Workato::Connector::Sdk::Connector.from_file("connector.rb", settings) }
  let(:settings) { Workato::Connector::Sdk::Settings.from_default_file }

  let(:object_definition) { connector.object_definition.compound_type }

  context 'Given event config input' do
    subject(:schema_fields) { object_definition.fields(settings, config_fields) }
    let(:config_fields) { { type: :event } }
    let(:expected_schema) { JSON.parse(File.read('fixtures/object_definitions/compound_type/definition_event.json')) }

    it 'returns schema definition' do
      expect(schema_fields).to be_kind_of(Array)
      expect(schema_fields).to match_array(expected_schema)
    end
  end
end

# pick_lists の lambda 関数のテスト

connector_spec.rb 内の pick_lists の lambda 関数をトリガーするには、connector.pick_lists.<pick_list_name>(settings, **args) を使用します。

CLI コマンド workato generate test を使用すると、spec フォルダーにスタブを自動生成できます。それぞれの pick_lists の lambda 関数には、各々に固有の spec ファイルが用意されます。

属性 説明
用途 コネクター内の特定の pick_lists の lambda 関数を呼び出す。
入力 settings - 設定インスタンス

設定可能。pick_list の引数による
出力 pick_lists の lambda 関数の出力
使用方法 connector.pick_lists.<pick_list_name>(settings, **args)

# 例: RSpec テスト - pick_lists の lambda 関数のテスト

# frozen_string_literal: true

RSpec.describe "pick_lists/events", :vcr do
  let(:connector) { Workato::Connector::Sdk::Connector.from_file("connector.rb", settings) }
  let(:settings) { Workato::Connector::Sdk::Settings.from_default_file }

  subject(:pick_list) { connector.pick_lists.events(settings, config_fields) }


  context 'Given configuration parameter' do
    let(:config_fields) { { type: :city } }
    let(:expected_picklist) { JSON.parse(File.read('fixtures/pick_lists/events/pick_list_city.json')) }

    it 'returns schema definition' do
      expect(pick_list).to be_kind_of(Array)
      expect(pick_list).to match_array(expected_picklist)
    end
  end
end


Last updated: 2023/12/20 23:22:08