Class: Temporalio::Testing::WorkflowEnvironment

Inherits:
Object
  • Object
show all
Defined in:
lib/temporalio/testing/workflow_environment.rb

Overview

Test environment with a Temporal server for running workflows and more.

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(client) ⇒ WorkflowEnvironment

Create workflow environment to an existing server with the given client.

Parameters:

  • client (Client) —

    Client to existing server.



242
243
244
# File 'lib/temporalio/testing/workflow_environment.rb', line 242

def initialize(client)
  @client = client
end

Instance Attribute Details

#client ⇒ Client (readonly)

Returns Client for the server.

Returns:

  • (Client) —

    Client for the server.



22
23
24
# File 'lib/temporalio/testing/workflow_environment.rb', line 22

def client
  @client
end

Class Method Details

.start_local(namespace: 'default', data_converter: Converters::DataConverter.default, interceptors: [], logger: Logger.new($stdout, level: Logger::WARN), default_workflow_query_reject_condition: nil, ip: '127.0.0.1', port: nil, ui: false, ui_port: nil, search_attributes: [], runtime: Runtime.default, dev_server_existing_path: nil, dev_server_database_filename: nil, dev_server_log_format: 'pretty', dev_server_log_level: 'warn', dev_server_download_version: 'default', dev_server_download_dest_dir: nil, dev_server_extra_args: [], dev_server_download_ttl: nil, dev_server_startup_timeout: nil) {|environment| ... } ⇒ WorkflowEnvironment, Object

Start a local dev server. This is a full Temporal dev server from the CLI that by default downloaded to tmp if not already present. The dev server is run as a child process. All options that start with dev_server_ are for this specific implementation. If that implementation changes, these options and their values may no longer be valid.

If a block is given it is passed the environment and the environment is shut down after. If a block is not given, the environment is returned and #shutdown needs to be called manually.

Parameters:

  • namespace (String) (defaults to: 'default') —

    Namespace for the server.

  • data_converter (Converters::DataConverter) (defaults to: Converters::DataConverter.default) —

    Data converter for the client.

  • interceptors (Array<Client::Interceptor>) (defaults to: []) —

    Interceptors for the client.

  • logger (Logger) (defaults to: Logger.new($stdout, level: Logger::WARN)) —

    Logger for the client.

  • default_workflow_query_reject_condition (WorkflowQueryRejectCondition, nil) (defaults to: nil) —

    Default rejection condition for the client.

  • ip (String) (defaults to: '127.0.0.1') —

    IP to bind to.

  • port (Integer, nil) (defaults to: nil) —

    Port to bind on, or nil for random.

  • ui (Boolean) (defaults to: false) —

    If true, also starts the UI.

  • ui_port (Integer, nil) (defaults to: nil) —

    Port to bind on if ui is true, or nil for random.

  • search_attributes (Array<SearchAttributes::Key>) (defaults to: []) —

    Search attributes to make available on start.

  • runtime (Runtime) (defaults to: Runtime.default) —

    Runtime for the server and client.

  • dev_server_existing_path (String, nil) (defaults to: nil) —

    Existing CLI path to use instead of downloading and caching to tmp.

  • dev_server_database_filename (String, nil) (defaults to: nil) —

    Persistent SQLite filename to use across local server runs. Default of nil means in-memory only.

  • dev_server_log_format (String) (defaults to: 'pretty') —

    Log format for CLI dev server.

  • dev_server_log_level (String) (defaults to: 'warn') —

    Log level for CLI dev server.

  • dev_server_download_version (String) (defaults to: 'default') —

    Version of dev server to download and cache.

  • dev_server_download_dest_dir (String, nil) (defaults to: nil) —

    Where to download. Defaults to tmp.

  • dev_server_extra_args (Array<String>) (defaults to: []) —

    Any extra arguments for the CLI dev server.

  • dev_server_download_ttl (Float, nil) (defaults to: nil) —

    How long the automatic download should be cached for. If nil, cached indefinitely.

  • dev_server_startup_timeout (Float, nil) (defaults to: nil) —

    Seconds to wait for startup, excluding download time. Defaults to 5.

Yields:

  • (environment) —

    If a block is given, it is called with the environment and upon complete the environment is shutdown.

Yield Parameters:

Returns:

  • (WorkflowEnvironment, Object) —

    Started local server environment with client if there was no block given, or block result if block was given.



64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
# File 'lib/temporalio/testing/workflow_environment.rb', line 64

def self.start_local(
  namespace: 'default',
  data_converter: Converters::DataConverter.default,
  interceptors: [],
  logger: Logger.new($stdout, level: Logger::WARN),
  default_workflow_query_reject_condition: nil,
  ip: '127.0.0.1',
  port: nil,
  ui: false, # rubocop:disable Naming/MethodParameterName
  ui_port: nil,
  search_attributes: [],
  runtime: Runtime.default,
  dev_server_existing_path: nil,
  dev_server_database_filename: nil,
  dev_server_log_format: 'pretty',
  dev_server_log_level: 'warn',
  dev_server_download_version: 'default',
  dev_server_download_dest_dir: nil,
  dev_server_extra_args: [],
  dev_server_download_ttl: nil,
  dev_server_startup_timeout: nil,
  &
)
  # Add search attribute args
  unless search_attributes.empty?
    dev_server_extra_args += search_attributes.flat_map do |key|
      raise 'Search attribute must be Key' unless key.is_a?(SearchAttributes::Key)

      ['--search-attribute', "#{key.name}=#{SearchAttributes::IndexedValueType::PROTO_NAMES[key.type]}"]
    end
  end

  server_options = Internal::Bridge::Testing::EphemeralServer::StartDevServerOptions.new(
    existing_path: dev_server_existing_path,
    sdk_name: 'sdk-ruby',
    sdk_version: VERSION,
    download_version: dev_server_download_version,
    download_dest_dir: dev_server_download_dest_dir,
    namespace:,
    ip:,
    port:,
    database_filename: dev_server_database_filename,
    ui:,
    ui_port: ui ? ui_port : nil,
    log_format: dev_server_log_format,
    log_level: dev_server_log_level,
    extra_args: dev_server_extra_args,
    download_ttl: dev_server_download_ttl,
    startup_timeout: dev_server_startup_timeout
  )
  _with_core_server(
    core_server: Internal::Bridge::Testing::EphemeralServer.start_dev_server(
      runtime._core_runtime, server_options
    ),
    namespace:,
    data_converter:,
    interceptors:,
    logger:,
    default_workflow_query_reject_condition:,
    runtime:,
    supports_time_skipping: false,
    & # steep:ignore
  )
end

.start_time_skipping(data_converter: Converters::DataConverter.default, interceptors: [], logger: Logger.new($stdout, level: Logger::WARN), default_workflow_query_reject_condition: nil, port: nil, runtime: Runtime.default, test_server_existing_path: nil, test_server_download_version: 'default', test_server_download_dest_dir: nil, test_server_extra_args: [], test_server_download_ttl: nil, test_server_startup_timeout: nil) {|environment| ... } ⇒ WorkflowEnvironment, Object

Start a time-skipping test server. This server can skip time but may not have all of the Temporal features of the start_local form. By default, the server is downloaded to tmp if not already present. The test server is run as a child process. All options that start with test_server_ are for this specific implementation. If that implementation changes, these options and their values may no longer be valid.

If a block is given it is passed the environment and the environment is shut down after. If a block is not given, the environment is returned and #shutdown needs to be called manually.

Parameters:

  • data_converter (Converters::DataConverter) (defaults to: Converters::DataConverter.default) —

    Data converter for the client.

  • interceptors (Array<Client::Interceptor>) (defaults to: []) —

    Interceptors for the client.

  • logger (Logger) (defaults to: Logger.new($stdout, level: Logger::WARN)) —

    Logger for the client.

  • default_workflow_query_reject_condition (WorkflowQueryRejectCondition, nil) (defaults to: nil) —

    Default rejection condition for the client.

  • port (Integer, nil) (defaults to: nil) —

    Port to bind on, or nil for random.

  • runtime (Runtime) (defaults to: Runtime.default) —

    Runtime for the server and client.

  • test_server_existing_path (String, nil) (defaults to: nil) —

    Existing CLI path to use instead of downloading and caching to tmp.

  • test_server_download_version (String) (defaults to: 'default') —

    Version of test server to download and cache.

  • test_server_download_dest_dir (String, nil) (defaults to: nil) —

    Where to download. Defaults to tmp.

  • test_server_extra_args (Array<String>) (defaults to: []) —

    Any extra arguments for the test server.

  • test_server_download_ttl (Float, nil) (defaults to: nil) —

    How long the automatic download should be cached for. If nil, cached indefinitely.

  • test_server_startup_timeout (Float, nil) (defaults to: nil) —

    Seconds to wait for startup, excluding download time. Defaults to 5.

Yields:

  • (environment) —

    If a block is given, it is called with the environment and upon complete the environment is shutdown.

Yield Parameters:

Returns:

  • (WorkflowEnvironment, Object) —

    Started local server environment with client if there was no block given, or block result if block was given.



160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
# File 'lib/temporalio/testing/workflow_environment.rb', line 160

def self.start_time_skipping(
  data_converter: Converters::DataConverter.default,
  interceptors: [],
  logger: Logger.new($stdout, level: Logger::WARN),
  default_workflow_query_reject_condition: nil,
  port: nil,
  runtime: Runtime.default,
  test_server_existing_path: nil,
  test_server_download_version: 'default',
  test_server_download_dest_dir: nil,
  test_server_extra_args: [],
  test_server_download_ttl: nil,
  test_server_startup_timeout: nil,
  &
)
  server_options = Internal::Bridge::Testing::EphemeralServer::StartTestServerOptions.new(
    existing_path: test_server_existing_path,
    sdk_name: 'sdk-ruby',
    sdk_version: VERSION,
    download_version: test_server_download_version,
    download_dest_dir: test_server_download_dest_dir,
    port:,
    extra_args: test_server_extra_args,
    download_ttl: test_server_download_ttl,
    startup_timeout: test_server_startup_timeout
  )
  _with_core_server(
    core_server: Internal::Bridge::Testing::EphemeralServer.start_test_server(
      runtime._core_runtime, server_options
    ),
    namespace: 'default',
    data_converter:,
    interceptors:,
    logger:,
    default_workflow_query_reject_condition:,
    runtime:,
    supports_time_skipping: true,
    & # steep:ignore
  )
end

Instance Method Details

#auto_time_skipping_disabled { ... } ⇒ Object

Run a block with automatic time skipping disabled. This just runs the block for environments that don't support time skipping.

Yields:

  • Block to run.

Returns:

  • (Object) —

    Result of the block.



320
321
322
323
324
# File 'lib/temporalio/testing/workflow_environment.rb', line 320

def auto_time_skipping_disabled(&)
  raise 'Block required' unless block_given?

  yield
end

#create_nexus_endpoint(name:, task_queue:) ⇒ Temporalio::Api::Nexus::V1::Endpoint

Create Nexus endpoint on this test environment.

WARNING: Nexus support is experimental.

Parameters:

  • name (String) —

    Endpoint name.

  • task_queue (String) —

    Task queue for the endpoint.

Returns:



283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
# File 'lib/temporalio/testing/workflow_environment.rb', line 283

def create_nexus_endpoint(name:, task_queue:)
  resp = client.connection.operator_service.create_nexus_endpoint(
    Temporalio::Api::OperatorService::V1::CreateNexusEndpointRequest.new(
      spec: Temporalio::Api::Nexus::V1::EndpointSpec.new(
        name:,
        target: Temporalio::Api::Nexus::V1::EndpointTarget.new(
          worker: Temporalio::Api::Nexus::V1::EndpointTarget::Worker.new(
            namespace: client.namespace,
            task_queue:
          )
        )
      )
    )
  )
  resp.endpoint
end

#current_time ⇒ Time

Current time of the environment.

If this server supports time skipping, this will be the current time as known to the environment. If it does not, this is a standard Time.now.

Returns:

  • (Time) —

    Current time.



272
273
274
# File 'lib/temporalio/testing/workflow_environment.rb', line 272

def current_time
  Time.now
end

#delete_nexus_endpoint(endpoint) ⇒ Object

Delete Nexus endpoint on this test environment.

WARNING: Nexus support is experimental.

Parameters:



305
306
307
308
309
310
311
312
313
# File 'lib/temporalio/testing/workflow_environment.rb', line 305

def delete_nexus_endpoint(endpoint)
  client.connection.operator_service.delete_nexus_endpoint(
    Temporalio::Api::OperatorService::V1::DeleteNexusEndpointRequest.new(
      id: endpoint.id,
      version: endpoint.version
    )
  )
  nil
end

#shutdown ⇒ Object

Shutdown this workflow environment.



247
248
249
# File 'lib/temporalio/testing/workflow_environment.rb', line 247

def shutdown
  # Do nothing by default
end

#sleep(duration) ⇒ Object

Advanced time.

If this server supports time skipping, this will immediately advance time and return. If it does not, this is a standard sleep.

Parameters:

  • duration (Float) —

    Duration seconds.



262
263
264
# File 'lib/temporalio/testing/workflow_environment.rb', line 262

def sleep(duration)
  Kernel.sleep(duration)
end

#supports_time_skipping? ⇒ Boolean

Returns Whether this environment supports time skipping.

Returns:

  • (Boolean) —

    Whether this environment supports time skipping.



252
253
254
# File 'lib/temporalio/testing/workflow_environment.rb', line 252

def supports_time_skipping?
  false
end