feat(testing): Use temporal CLI to power local test environment (#1077)

BREAKING CHANGE: the `TemporaliteConfig` interface was deleted but it likely was not directly referenced as only the deprecated `create` method accepted it.

Closes #1055

Author: bergundy

.github/workflows/ci.yml

@@ -70,7 +70,7 @@ jobs:
 
       - run: npm test
         env:
-          # TODO: Run integration tests on MacOS / Windows probably using temporalite
+          # NOTE: Newer tests start their own server and are not subject to this env var.
           RUN_INTEGRATION_TESTS: ${{ startsWith(matrix.os, 'ubuntu') }}
           REUSE_V8_CONTEXT: ${{ matrix.reuse-v8-context }}
 

packages/core-bridge/Cargo.lock

@@ -14,14 +14,15 @@ use temporal_sdk_core::{
     },
     api::worker::{WorkerConfig, WorkerConfigBuilder},
     ephemeral_server::{
-        TemporaliteConfig, TemporaliteConfigBuilder, TestServerConfig, TestServerConfigBuilder,
+        TemporalDevServerConfig, TemporalDevServerConfigBuilder, TestServerConfig,
+        TestServerConfigBuilder,
     },
     ClientOptions, ClientOptionsBuilder, ClientTlsConfig, RetryConfig, TlsConfig, Url,
 };
 
 pub enum EphemeralServerConfig {
     TestServer(TestServerConfig),
-    Temporalite(TemporaliteConfig),
+    DevServer(TemporalDevServerConfig),
 }
 
 pub trait ArrayHandleConversionsExt {
@@ -403,8 +404,8 @@ impl ObjectHandleConversionsExt for Handle<'_, JsObject> {
 
         let server_type = js_value_getter!(cx, self, "type", JsString);
         match server_type.as_str() {
-            "temporalite" => {
-                let mut config = TemporaliteConfigBuilder::default();
+            "dev-server" => {
+                let mut config = TemporalDevServerConfigBuilder::default();
                 config.exe(executable).port(port);
 
                 if let Some(extra_args) = js_optional_getter!(cx, self, "extraArgs", JsArray) {
@@ -427,9 +428,9 @@ impl ObjectHandleConversionsExt for Handle<'_, JsObject> {
                 }
 
                 match config.build() {
-                    Ok(config) => Ok(EphemeralServerConfig::Temporalite(config)),
+                    Ok(config) => Ok(EphemeralServerConfig::DevServer(config)),
                     Err(err) => {
-                        cx.throw_type_error(format!("Invalid temporalite config: {:?}", err))
+                        cx.throw_type_error(format!("Invalid dev server config: {:?}", err))
                     }
                 }
             }
@@ -450,7 +451,7 @@ impl ObjectHandleConversionsExt for Handle<'_, JsObject> {
                 }
             }
             s => cx.throw_type_error(format!(
-                "Invalid ephemeral server type: {}, expected 'temporalite' or 'time-skipping'",
+                "Invalid ephemeral server type: {}, expected 'dev-server' or 'time-skipping'",
                 s
             )),
         }

packages/core-bridge/sdk-core

@@ -273,9 +273,7 @@ pub fn start_bridge_loop(
                             EphemeralServerConfig::TestServer(config) => {
                                 config.start_server().await
                             }
-                            EphemeralServerConfig::Temporalite(config) => {
-                                config.start_server().await
-                            }
+                            EphemeralServerConfig::DevServer(config) => config.start_server().await,
                         };
                         match result {
                             Err(err) => {

packages/core-bridge/src/conversions.rs

@@ -381,10 +381,10 @@ export interface TimeSkippingServerConfig {
 }
 
 /**
- * Configuration for temporalite.
+ * Configuration for the Temporal CLI dev server.
  */
-export interface TemporaliteConfig {
-  type: 'temporalite';
+export interface DevServerConfig {
+  type: 'dev-server';
   executable?: EphemeralServerExecutable;
   /**
    * Namespace to use - created at startup.
@@ -399,11 +399,13 @@ export interface TemporaliteConfig {
    */
   ip?: string;
   /**
-   * Sqlite DB filename if persisting or non-persistent if none.
+   * Sqlite DB filename if persisting or non-persistent if none (default).
    */
   db_filename?: string;
   /**
    * Whether to enable the UI.
+   *
+   * @default false
    */
   ui?: boolean;
   /**
@@ -424,9 +426,9 @@ export interface TemporaliteConfig {
 /**
  * Configuration for spawning an ephemeral Temporal server.
  *
- * Both the time-skipping test server and temporalite are supported.
+ * Both the time-skipping test server and Temporal CLI dev server are supported.
  */
-export type EphemeralServerConfig = TimeSkippingServerConfig | TemporaliteConfig;
+export type EphemeralServerConfig = TimeSkippingServerConfig | DevServerConfig;
 
 export interface Worker {
   type: 'Worker';

packages/core-bridge/src/runtime.rs

@@ -115,8 +115,7 @@ export function runIntegrationTests(codec?: PayloadCodec): void {
       metaClient,
     };
 
-    // In case we're running with temporalite or other non default server.
-    // NOTE: at the time this was added temporalite did not expose the grpc OperatorService.
+    // In case we're running with a server that doesn't use the docker-compose setup.
     try {
       await connection.operatorService.addSearchAttributes({
         namespace: 'default',

packages/core-bridge/ts/index.ts

@@ -41,7 +41,7 @@ test('TestEnvironment sets up test server and is able to run a single workflow',
   await runSimpleWorkflow(t, testEnv);
 });
 
-test('TestEnvironment sets up temporalite and is able to run a single workflow', async (t) => {
+test('TestEnvironment sets up dev server and is able to run a single workflow', async (t) => {
   const testEnv = await TestWorkflowEnvironment.createLocal();
   await runSimpleWorkflow(t, testEnv);
 });
@@ -51,8 +51,8 @@ test.todo('TestEnvironment sets up test server with specified port');
 test.todo('TestEnvironment sets up test server with latest version');
 test.todo('TestEnvironment sets up test server from executable path');
 
-test.todo('TestEnvironment sets up temporalite with extra args');
-test.todo('TestEnvironment sets up temporalite with latest version');
-test.todo('TestEnvironment sets up temporalite from executable path');
-test.todo('TestEnvironment sets up temporalite with custom log level');
-test.todo('TestEnvironment sets up temporalite with custom namespace, IP, db filename, and UI');
+test.todo('TestEnvironment sets up dev server with extra args');
+test.todo('TestEnvironment sets up dev server with latest version');
+test.todo('TestEnvironment sets up dev server from executable path');
+test.todo('TestEnvironment sets up dev server with custom log level');
+test.todo('TestEnvironment sets up dev server with custom namespace, IP, db filename, and UI');

packages/test/src/integration-tests.ts

@@ -29,13 +29,13 @@ import {
   EphemeralServer,
   EphemeralServerConfig,
   getEphemeralServerTarget,
-  TemporaliteConfig,
+  DevServerConfig,
   TimeSkippingServerConfig,
 } from '@temporalio/core-bridge';
 import { filterNullAndUndefined } from '@temporalio/common/lib/internal-non-workflow';
 import { Connection, TestService } from './connection';
 
-export { TimeSkippingServerConfig, TemporaliteConfig, EphemeralServerExecutable } from '@temporalio/core-bridge';
+export { TimeSkippingServerConfig, DevServerConfig, EphemeralServerExecutable } from '@temporalio/core-bridge';
 export { EphemeralServerConfig };
 
 export interface TimeSkippingWorkflowClientOptions extends WorkflowClientOptions {
@@ -121,8 +121,8 @@ export type ClientOptionsForTestEnv = Omit<ClientOptions, 'namespace' | 'connect
 /**
  * Options for {@link TestWorkflowEnvironment.create}
  */
-type TestWorkflowEnvironmentOptions = {
-  server?: EphemeralServerConfig;
+export type TestWorkflowEnvironmentOptions = {
+  server: EphemeralServerConfig;
   client?: ClientOptionsForTestEnv;
 };
 
@@ -138,17 +138,14 @@ export type TimeSkippingTestWorkflowEnvironmentOptions = {
  * Options for {@link TestWorkflowEnvironment.createLocal}
  */
 export type LocalTestWorkflowEnvironmentOptions = {
-  server?: Omit<TemporaliteConfig, 'type'>;
+  server?: Omit<DevServerConfig, 'type'>;
   client?: ClientOptionsForTestEnv;
 };
 
 export type TestWorkflowEnvironmentOptionsWithDefaults = Required<TestWorkflowEnvironmentOptions>;
 
 function addDefaults(opts: TestWorkflowEnvironmentOptions): TestWorkflowEnvironmentOptionsWithDefaults {
   return {
-    server: {
-      type: 'time-skipping',
-    },
     client: {},
     ...opts,
   };
@@ -201,11 +198,12 @@ export class TestWorkflowEnvironment {
     public readonly supportsTimeSkipping: boolean,
     protected readonly server: EphemeralServer,
     connection: Connection,
-    nativeConnection: NativeConnection
+    nativeConnection: NativeConnection,
+    namespace: string | undefined
   ) {
     this.connection = connection;
     this.nativeConnection = nativeConnection;
-    this.namespace = options.server.type === 'temporalite' ? options.server.namespace : undefined;
+    this.namespace = namespace;
     this.client = new TestEnvClient({
       connection,
       namespace: this.namespace,
@@ -239,8 +237,11 @@ export class TestWorkflowEnvironment {
    * In the future, the test server implementation may be changed to another implementation.
    */
   static async createTimeSkipping(opts?: TimeSkippingTestWorkflowEnvironmentOptions): Promise<TestWorkflowEnvironment> {
-    // eslint-disable-next-line deprecation/deprecation
-    return await this.create({ server: { type: 'time-skipping', ...opts?.server }, client: opts?.client });
+    return await this.create({
+      server: { type: 'time-skipping', ...opts?.server },
+      client: opts?.client,
+      supportsTimeSkipping: true,
+    });
   }
 
   /**
@@ -250,38 +251,42 @@ export class TestWorkflowEnvironment {
    * {@link createTimeSkipping} does. {@link supportsTimeSkipping} will always return `false` for this environment.
    * {@link sleep} will sleep the actual amount of time and {@link currentTimeMs} will return the current time.
    *
-   * Internally, this uses [Temporalite](https://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 {@link LocalTestWorkflowEnvironmentOptions.server.executable.type} is
-   * `'cached-download'`.
+   * This local environment will be powered by [Temporal CLI](https://github.com/temporalio/cli), which is a
+   * self-contained executable for Temporal. By default, Temporal's database will not be persisted to disk, and no UI
+   * will be started.
    *
-   * In the future, the Temporalite implementation may be changed to another implementation.
+   * The CLI executable will be downloaded and cached to a temporary directory. See
+   * {@link LocalTestWorkflowEnvironmentOptions.server.executable.type} if you'd prefer to provide the CLI executable
+   * yourself.
    */
   static async createLocal(opts?: LocalTestWorkflowEnvironmentOptions): Promise<TestWorkflowEnvironment> {
     // eslint-disable-next-line deprecation/deprecation
-    return await this.create({ server: { type: 'temporalite', ...opts?.server }, client: opts?.client });
+    return await this.create({
+      server: { type: 'dev-server', ...opts?.server },
+      client: opts?.client,
+      namespace: opts?.server?.namespace,
+      supportsTimeSkipping: false,
+    });
   }
 
   /**
    * Create a new test environment
-   *
-   * @deprecated - use {@link createTimeSkipping} or {@link createLocal}
    */
-  static async create(opts?: TestWorkflowEnvironmentOptions): Promise<TestWorkflowEnvironment> {
-    const optsWithDefaults = addDefaults(filterNullAndUndefined(opts ?? {}));
+  private static async create(
+    opts: TestWorkflowEnvironmentOptions & {
+      supportsTimeSkipping: boolean;
+      namespace?: string;
+    }
+  ): Promise<TestWorkflowEnvironment> {
+    const { supportsTimeSkipping, namespace, ...rest } = opts;
+    const optsWithDefaults = addDefaults(filterNullAndUndefined(rest));
     const server = await Runtime.instance().createEphemeralServer(optsWithDefaults.server);
     const address = getEphemeralServerTarget(server);
 
     const nativeConnection = await NativeConnection.connect({ address });
     const connection = await Connection.connect({ address });
 
-    return new this(
-      optsWithDefaults,
-      optsWithDefaults.server.type === 'time-skipping',
-      server,
-      connection,
-      nativeConnection
-    );
+    return new this(optsWithDefaults, supportsTimeSkipping, server, connection, nativeConnection, namespace);
   }
 
   /**