Module: Temporalio::Testing

Defined in:
lib/temporalio/testing.rb,
lib/temporalio/testing/time_skipping_handle.rb,
lib/temporalio/testing/workflow_environment.rb,
lib/temporalio/testing/time_skipping_interceptor.rb

Defined Under Namespace

Classes: TimeSkippingHandle, TimeSkippingInterceptor, WorkflowEnvironment

Constant Summary collapse

DEFAULT_NAMESPACE = 
'default'.freeze

Class Method Summary collapse

Class Method Details

.start_local_environment(namespace: DEFAULT_NAMESPACE, ip: '127.0.0.1', port: nil, download_dir: nil, ui: false, temporalite_existing_path: nil, temporalite_database_filename: nil, temporalite_log_format: 'pretty', temporalite_log_level: 'warn', temporalite_download_version: 'default', temporalite_extra_args: []) { ... } ⇒ Temporalio::Testing::WorkflowEnvironment

Start a full Temporal server locally, downloading if necessary.

This environment is good for testing full server capabilities, but does not support time skipping like start_time_skipping does. Temporalio::Testing::WorkflowEnvironment#supports_time_skipping will always return ‘false` for this environment. Temporalio::Testing::WorkflowEnvironment#sleep will sleep the actual amount of time and Temporalio::Testing::WorkflowEnvironment#get_current_time` will return the current time.

Internally, this uses [Temporalite](github.com/temporalio/temporalite). Which is a self-contained binary for Temporal using Sqlite persistence. This will download Temporalite to a temporary directory by default if it has not already been downloaded before and ‘:existing_path` is not set.

In the future, the Temporalite implementation may be changed to another implementation. Therefore, all ‘temporalite_` prefixed parameters are Temporalite specific and may not apply to newer versions.

Parameters:

  • namespace (String) (defaults to: DEFAULT_NAMESPACE) —

    Namespace name to use for this environment.

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

    IP address to bind to, or 127.0.0.1 by default.

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

    Port number to bind to, or an OS-provided port by default.

  • download_dir (String) (defaults to: nil) —

    Directory to download binary to if a download is needed. If unset, this is the system’s temporary directory.

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

    If ‘true`, will start a UI in Temporalite.

  • temporalite_existing_path (String) (defaults to: nil) —

    Existing path to the Temporalite binary. If present, no download will be attempted to fetch the binary.

  • temporalite_database_filename (String) (defaults to: nil) —

    Path to the Sqlite database to use for Temporalite. Unset default means only in-memory Sqlite will be used.

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

    Log format for Temporalite.

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

    Log level to use for Temporalite.

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

    Specific Temporalite version to download. Defaults to ‘default` which downloads the version known to work best with this SDK.

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

    Extra arguments for the Temporalite binary.

Yields:

Returns:



53
54
55
56
57
58
59
60
61
62
63
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
 
# File 'lib/temporalio/testing.rb', line 53

def start_local_environment(
  namespace: DEFAULT_NAMESPACE,
  ip: '127.0.0.1',
  port: nil,
  download_dir: nil,
  ui: false,
  temporalite_existing_path: nil,
  temporalite_database_filename: nil,
  temporalite_log_format: 'pretty',
  temporalite_log_level: 'warn',
  temporalite_download_version: 'default',
  temporalite_extra_args: [],
  &block
)
  # TODO: Sync with the SDK's logger level when implemented
  runtime = Temporalio::Runtime.instance
  server = Temporalio::Bridge::TestServer.start_temporalite(
    runtime.core_runtime,
    temporalite_existing_path,
    'sdk-ruby',
    Temporalio::VERSION,
    temporalite_download_version,
    download_dir,
    namespace,
    ip,
    port,
    temporalite_database_filename,
    ui,
    temporalite_log_format,
    temporalite_log_level,
    temporalite_extra_args,
  )
  env = init_workflow_environment_for(server, namespace)

  return env unless block

  run_server(server, env, &block)
end

.start_time_skipping_environment(port: nil, download_dir: nil, test_server_existing_path: nil, test_server_download_version: 'default', test_server_extra_args: []) { ... } ⇒ Temporalio::Testing::WorkflowEnvironment

Note:

Auto time skipping is not yet implemented.

Start a time skipping workflow environment.

Time can be manually skipped forward using Temporalio::Testing::WorkflowEnvironment#sleep. The currently known time can be obtained via Temporalio::Testing::WorkflowEnvironment#get_current_time.

Internally, this environment lazily downloads a test-server binary for the current OS/arch into the temp directory if it is not already there. Then the executable is started and will be killed when Temporalio::Testing::WorkflowEnvironment#shutdown is called (which is implicitly done if a block is provided to this method).

Users can reuse this environment for testing multiple independent workflows, but not concurrently. Time skipping, which is automatically done when awaiting a workflow result (pending implementation) and manually done on Temporalio::Testing::WorkflowEnvironment#sleep, is global to the environment, not to the workflow under test.

In the future, the test server implementation may be changed to another implementation. Therefore, all ‘test_server_` prefixed parameters are test server specific and may not apply to newer versions.

Parameters:

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

    Port number to bind to, or an OS-provided port by default.

  • download_dir (String) (defaults to: nil) —

    Directory to download binary to if a download is needed. If unset, this is the system’s temporary directory.

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

    Existing path to the test server binary. If present, no download will be attempted to fetch the binary.

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

    Specific test server version to download. Defaults to ‘default` which downloads the version known to work best with this SDK.

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

    Extra arguments for the test server binary.

Yields:

Returns:



131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
 
# File 'lib/temporalio/testing.rb', line 131

def start_time_skipping_environment(
  port: nil,
  download_dir: nil,
  test_server_existing_path: nil,
  test_server_download_version: 'default',
  test_server_extra_args: [],
  &block
)
  # TODO: Use interceptors to inject a time skipping WorkflowHandle.
  runtime = Temporalio::Runtime.instance
  server = Temporalio::Bridge::TestServer.start(
    runtime.core_runtime,
    test_server_existing_path,
    'sdk-ruby',
    Temporalio::VERSION,
    test_server_download_version,
    download_dir,
    port,
    test_server_extra_args,
  )
  env = init_workflow_environment_for(server, DEFAULT_NAMESPACE)

  return env unless block

  run_server(server, env, &block)
end