# SDK - プロジェクトのディレクトリとファイルのリファレンス
SDK gem を使用して作成されたコネクタープロジェクトは通常、以下のような構成となります。
. # root ├── connector.rb ├── fixtures ├── Gemfile ├── Gemfile.lock ├── logo.png ├── master.key ├── README.md ├── settings.yaml.enc ├── spec | ├── connector_spec.rb | └── spec_helper.rb ├── tape_library ├── .github ├── .gitignore └── .rspec
Copied!
それぞれのファイルやディレクトリの役割について、以下に概要を示します。
ファイル/ディレクトリ | 作成者/作成手段 | 説明 |
---|---|---|
connector.rb | workato new | 実際のコネクターコードを格納します。これは Workato 内にあるコネクターコードの複製となっているはずです。 |
fixtures | workato new | RSpec や CLI のための入力/出力 JSON ファイルを格納します。サンプルファイルと詳細情報についてはこちらから確認できます。 |
Gemfile | workato new | プロジェクトに必要な gem (依存関係) を宣言します。これは RSpec の実行に必要となります。サンプルファイルと詳細情報についてはこちらから確認できます。 |
Gemfile.lock | workato new | バージョンや依存関係の依存関係といった、gem の依存関係データを格納します。このファイルは、プロジェクト作成時に自動で作成されます。 |
logo.png | ユーザー | コネクターのロゴ。workato push を通して Workato ワークスペースと同期されると、これがコネクターのデフォルトのロゴ画像として使用されます。
|
master.key | workato new | ファイルの暗号化に使用される暗号化キーを格納します。暗号化されるファイルの例には、資格情報をはじめとする機密データ (アカウントのプロパティなど) があります。
注: プロジェクトの設定時に secure が選択された場合にのみ作成されます。
|
README.md | ユーザー | コネクターの機能や使用方法を書き記すために用いられます。workato push を通して Workato ワークスペースと同期されると、これがコネクターの説明のデフォルトファイルとして使用されます。
|
settings.yaml.enc または settings.yaml | コネクターのテストに用いられる資格情報を格納します。サンプルファイルと詳細情報についてはこちらから確認できます。
注: プロジェクトのセットアップ時に secure が選択された場合、これは .yaml.enc ファイルになります。それ以外の場合は .yaml ファイルになります。
| |
spec | workato new | RSpec テストファイルを格納します。rSpec は、SDK gem と組み合わせて使用することでコネクターの単体テストを定義、記述、実行できる Ruby テストツールです。 |
spec/connector_spec.rb | workato new | コネクターの単体テストすべてを格納します。このファイルが、メインの RSpec ファイルです。サンプルファイルと詳細情報についてはこちらから確認できます。
このファイルは、テストを整理するために複数のファイルやフォルダーに分けることもできます。すべての仕様テストは bundle exec rspec コマンドを使って実行できます。
|
spec/spec_helper.rb | workato new | RSpec の実行前に毎回設定する必要があるコマンドすべてを格納します。サンプルファイルと詳細情報についてはこちらから確認できます。 |
tape_library | RSpec | VCR カセットを格納します。VCR カセットは、記録された API リクエストと後続のレスポンスに関するすべての情報を格納したファイルです。これらのリクエストは、単体テストの安定のために欠かせません。詳細については VCR のドキュメントを参照してください。 |
.github | ユーザー | GitHub を利用している場合に使われます。ユーザーの GitHub アクションワークフローに関する情報を格納します。 |
.gitignore | workato new | Git にプッシュすべきではないファイルやディレクトリの名前を格納します。サンプルファイルと詳細情報についてはこちらから確認できます。
注: プロジェクトに master.key がある場合は、Workato のセキュリティベストプラクティスに従い、それをこのファイルに追加することが推奨されます。
|
.rspec | workato new | 実行時に RSpec に渡す標準オプションを格納します。フラグには以下のようなものがあります。
|
# connector_spec.rb
connector_spec.rb
ファイルは workato new
の実行時に作成され、コネクターの単体テストを格納します。
以下にファイル内容の例を挙げます。
# frozen_string_literal: true 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 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
Copied!
また、workato generate test
を使用して RSpec テストスタブを生成することもできます。これにより、コネクターのインスタンス化や設定といった手間のかかる作業の大部分を処理することができます。
単体テストをどのように書くかは、最終的にはユーザー次第です。作業を開始するための参考情報については、こちらのチュートリアルを参照してください (opens new window)。
# fixtures
/fixtures
フォルダーの用途は、コネクターの各部分をテストするために使用される入力/出力 JSON ファイルを格納することです。その各部分としては、たとえばアクション、トリガー、メソッドなどが挙げられます。
入力 JSON ファイルは、手動で作成する必要があります。これはユーザー自身で設計することも、Cloud SDK のデバッガーコンソールを利用して作成することもできます。
出力 JSON ファイルは、--output
オプションを追加することで CLI コマンドから作成できます。以下に例を示します。
workato exec <PATH> --output
Copied!
/fixtures
フォルダーの内容の例を以下に示します。
├── fixtures │ ├── actions │ │ └── search_customers │ │ ├── input.json │ │ └── output.json │ ├── methods │ │ └── sample_method │ │ ├── input.json │ │ └── output.json │ ├── pick_lists │ │ └── dependent │ │ └── input.json │ └── triggers │ └── new_updated_object │ ├── customer_config.json │ ├── customer_input_poll.json │ ├── customer_input_poll_page.json │ ├── customer_output_fields.json │ ├── customer_output_poll.json │ └── customer_output_poll_page.json
Copied!
# GEMFILE
# frozen_string_literal: true source 'https://rubygems.org' gem 'rspec' gem 'vcr' gem 'workato-connector-sdk' gem 'webmock' gem 'timecop' gem 'byebug' gem 'rubocop' # Only if you want to use rubocop. Not added by default.
Copied!
# settings.yaml.enc、settings.yaml
settings.yaml.enc
/settings.yaml
ファイルは、テストに使用する資格情報を格納します。このファイルのデータは有効な YAML である必要があります。
# 資格情報のセットが1つの場合
資格情報のセットが1つだけの場合、それはルートレベルで定義できます。
api_key: valid_key domain: valid_domain
Copied!
# 資格情報のセットが複数の場合
資格情報のセットが複数ある場合、設定ファイルは以下のような構造にする必要があります。
[one_connection_name]: api_key: valid_key domain: valid_domain [second_connection_name]: api_key: invalid_key domain: invalid_domain
Copied!
# spec_helper.rb
spec_helper.rb
ファイルは workato new
の実行時に作成され、RSpec の実行で使用される一般的な属性を格納します。
このファイルでは少なくとも以下を require する必要があります。
'bundler/setup'
'workato-connector-sdk'
'json'
追加的な RSpec 設定の詳細については、RSpec リポジトリ (opens new window)を参照してください。
以下は、プロジェクトの HTTP モック動作として secure
が選択されたときに作成される spec_helper.rb
ファイルの例です。
このファイルは、プロジェクトの master.key
を利用してすべての VCR 記録を暗号化します。
ただし、secure
の記録モードはデフォルトでは none
になっています。つまり、新しい VCR カセットは記録されないということです。この動作を変更するには、環境変数 VCR_RECORD_MODE
を once
に設定してください。
# frozen_string_literal: true require 'bundler/setup' require 'json' require "webmock/rspec" require "timecop" require "vcr" require "workato-connector-sdk" require "workato/testing/vcr_encrypted_cassette_serializer" require "workato/testing/vcr_multipart_body_matcher" RSpec.configure do |config| # Enable flags like --only-failures and --next-failure config.example_status_persistence_file_path = ".rspec_status" # Disable RSpec exposing methods globally on `Module` and `main` config.disable_monkey_patching! config.expect_with :rspec do |c| c.syntax = :expect end end VCR.configure do |config| config.cassette_library_dir = "tape_library" config.hook_into :webmock config.cassette_serializers[:encrypted] = Workato::Testing::VCREncryptedCassetteSerializer.new config.register_request_matcher :headers_without_user_agent do |request1, request2| request1.headers.except("User-Agent") == request2.headers.except("User-Agent") end config.register_request_matcher :multipart_body do |request1, request2| Workato::Testing::VCRMultipartBodyMatcher.call(request1, request2) end config.default_cassette_options = { record: ENV.fetch('VCR_RECORD_MODE', :none).to_sym, serialize_with: :encrypted, match_requests_on: %i[uri headers_without_user_agent body] } config.configure_rspec_metadata! end
Copied!
# .gitignore
.gitignore
ファイルには、Git でプッシュすべきではないファイルやディレクトリのリストが格納されます。
注 : プロジェクトに master.key
ファイルがある場合は、リポジトリに誤ってコミットされないよう、それをこのファイルに追加してください。
/.bundle/ /.yardoc /_yardoc/ /coverage/ /doc/ /pkg/ /spec/reports/ /tmp/ master.key # rspec failure tracking .rspec_status
Copied!
Last updated: 2024/7/10 18:18:20