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

各ファイルまたはディレクトリの機能の概要:

ファイル/ディレクトリ作成日時説明
connector.rbVia workato new実際のコネクターコードを保存します。 これはWorkato内のコネクターコードの複製である必要があります。
fixturesVia workato newRSpecまたはCLI用の入力および出力JSONファイルを保存します。 サンプルファイルについては、fixturesセクションを参照してください。
GemfileVia workato newプロジェクトに必要なgem(依存関係)を宣言します。 これらはRSpecを実行するために必要です。 サンプルファイルについては、Gemfileセクションを参照してください。
Gemfile.lockVia workato newバージョンや依存関係の依存関係など、gemの依存関係データを保存します。 このファイルは、プロジェクトのビルド時に自動的に作成されます。
logo.pngBy youコネクターのロゴです。 workato pushを使用してWorkatoワークスペースと同期すると、これはコネクターのロゴ画像のデフォルトとして使用されます。
master.keyVia workato newファイルの暗号化に使用する暗号化キーを保存します。 これらのファイルには、認証情報やEnvironment propertiesなどのその他の機密データを含めることができます。

: プロジェクトのセットアップ中にsecureを選択した場合にのみ作成されます。
README.mdBy youコネクターの機能と使用方法を文書化するために使用します。 workato pushを使用してWorkatoワークスペースと同期すると、これはコネクターの説明のデフォルトファイルとして使用されます。
settings.yaml.enc or settings.yamlコネクターのテストに使用する認証情報を保存します。 サンプルファイルについては、settings.yamlセクションを参照してください。

: プロジェクトのセットアップ中にsecureを選択した場合、これは.yaml.encファイルになります。 それ以外の場合、これは.yamlファイルになります。
specVia workato newRSpecテストファイルを保存します。 RSpecはRubyのテストツールであり、SDK gemと組み合わせて使用して、コネクターのユニットテストを定義、作成、実行できます。
spec/connector_spec.rbVia workato newコネクターのすべてのユニットテストを保存します。 これはメインのRSpecファイルです。 サンプルファイルについては、connector_spec.rbセクションを参照してください。

テストを整理するのに役立つ場合は、このファイルを複数のファイルまたはフォルダに分割できます。 すべてのspecテストは、bundle exec rspecコマンドを使用して実行できます。
spec/spec_helper.rbVia workato new各RSpec実行前にセットアップする必要があるすべてのコマンドを保存します。 サンプルファイルについては、spec_helper.rbセクションを参照してください。
tape_libraryvia RSpec記録されたAPIリクエストとその後のレスポンスに関するすべての情報を含むファイルであるVCRカセットを保存します。 これらのリクエストは、安定したユニットテストに不可欠です。 詳細については、VCRドキュメントを参照してください。
.githubBy youGitHubを使用している場合に適用されます。 GitHubアクションワークフローに関する情報を保存します。
.gitignoreVia workato newGitにプッシュしないファイルやディレクトリの名前を保存します。 サンプルファイルについては、.gitignoreセクションを参照してください。

: プロジェクトにmaster.keyがある場合は、セキュリティのベストプラクティスに従って、このファイルに追加する必要があります。
.rspecVia workato new実行時にRSpecに渡す標準オプションを保存します。 フラグの例:
  • --format documentation - テストをグループ化できるようにします
  • --color - RSpec出力で色付けを有効にします
  • --require spec_helper - 各実行前にspec_helper.rbを必須にするようRSpec実行に指示します

connector_spec.rb

workato newの実行時に作成されるconnector_spec.rbファイルには、コネクターのユニットテストが含まれています。

サンプルファイルは次のようになります:

ruby
# 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

workato generate testを使用して、RSpecテストスタブを生成することもできます。 これは、コネクターや設定のインスタンス化など、面倒な処理の大部分を処理します。

最終的に、ユニットテストをどのように作成するかはユーザー次第です。 開始にあたってサポートが必要な場合は、このチュートリアルを確認してください


fixtures

/fixturesフォルダは、コネクターの一部をテストするために使用する入力および出力JSONファイルを保存するために使用されます。 これには、アクション、トリガー、メソッドなどが含まれます。

Input JSONファイルは手動で作成し、形成する必要があります。 自分で設計することも、Cloud SDKのTest codeタブを使用して構築することもできます。

Output JSONファイルは、--outputオプションを含めることでCLIコマンドから作成できます。 例:

shell
workato exec <PATH> --output

/fixturesフォルダは次のようになります:

shell
├── 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

GEMFILE

ruby
# 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.

settings.yaml.enc, settings.yaml

settings.yaml.enc/settings.yamlファイルは、テストに使用する認証情報を保存します。 このファイルのデータは有効なYAMLである必要があります。

単一の認証情報セット

認証情報のセットが1つだけの場合は、ルートレベルで定義できます:

yaml
api_key: valid_key
domain: valid_domain

複数の認証情報セット

認証情報のセットが複数ある場合、設定ファイルは次のような構造にする必要があります:

yaml
[one_connection_name]:
  api_key: valid_key
  domain: valid_domain
[second_connection_name]:
  api_key: invalid_key
  domain: invalid_domain

spec_helper.rb

workato newの実行時に作成されるspec_helper.rbファイルは、RSpec実行で使用する共通属性を保存します。

このファイルには、少なくとも次をrequireする必要があります:

  • 'bundler/setup'
  • 'workato-connector-sdk'
  • 'json'

追加のRSpec設定の詳細については、こちらのRSpecリポジトリを参照してください。

次の例は、プロジェクトに対してsecure HTTPモック動作が選択された場合に作成されるspec_helper.rbファイルを示しています。

このファイルは、プロジェクトのmaster.keyを使用してすべてのVCR記録を暗号化します。

ただし、デフォルトではsecureの記録モードはnoneです。 これは、新しいVCRカセットが記録されないことを意味します。 この動作を変更するには、VCR_RECORD_MODEEnvironment変数をonceに設定します。

ruby
# 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

.gitignore

.gitignoreファイルには、Git経由でプッシュしないファイルやディレクトリのリストが含まれています。

: プロジェクトにmaster.keyファイルがある場合は、誤ってリポジトリにコミットされないように、このファイルに追加する必要があります。

/.bundle/
/.yardoc
/_yardoc/
/coverage/
/doc/
/pkg/
/spec/reports/
/tmp/
master.key

# rspec failure tracking
.rspec_status

Last updated: