feat: prool/testcontainers

Author: jxom

.changeset/shaggy-eels-lead.md

@@ -0,0 +1,13 @@
+---
+"prool": minor
+---
+
+**Breaking:** Moved `Instance.tempoDocker` into `prool/testcontainers` entrypoint.
+
+```diff
+- import { Instance } from 'prool'
++ import { Instance } from 'prool/testcontainers'
+
+- Instance.tempoDocker
++ Instance.tempo
+```

package.json

@@ -7,7 +7,7 @@
     "check:types": "tsc",
     "dev": "zile dev",
     "postinstall": "pnpm dev",
-    "test": "vitest --testTimeout=100000"
+    "test": "vitest --testTimeout=10000"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.3.8",
@@ -43,6 +43,11 @@
       "src": "./src/index.ts",
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
+    },
+    "./testcontainers": {
+      "src": "./src/testcontainers/index.ts",
+      "types": "./dist/testcontainers/index.d.ts",
+      "default": "./dist/testcontainers/index.js"
     }
   },
   "dependencies": {

src/Instance.ts

@@ -2,7 +2,7 @@ import { EventEmitter } from 'eventemitter3'
 
 export { alto } from './instances/alto.js'
 export { anvil } from './instances/anvil.js'
-export { tempo, tempoDocker } from './instances/tempo.js'
+export { tempo } from './instances/tempo.js'
 
 type EventTypes = {
   exit: [code: number | null, signal: NodeJS.Signals | null]

src/instances/tempo.ts

@@ -1,10 +1,5 @@
 import * as os from 'node:os'
 import * as path from 'node:path'
-import {
-  GenericContainer,
-  type StartedTestContainer,
-  Wait,
-} from 'testcontainers'
 import * as Instance from '../Instance.js'
 import { deepAssign, toArgs } from '../internal/utils.js'
 import { execa } from '../processes/execa.js'
@@ -210,113 +205,3 @@ export declare namespace tempo {
     port?: number | undefined
   } & Record<string, unknown>
 }
-
-/**
- * Defines a Tempo instance.
- *
- * @example
- * ```ts
- * const instance = Instance.tempoDocker({ port: 8545 })
- * await instance.start()
- * // ...
- * await instance.stop()
- * ```
- */
-export const tempoDocker = Instance.define(
-  (parameters?: tempoDocker.Parameters) => {
-    const {
-      containerName = `tempo.${crypto.randomUUID()}`,
-      image = 'ghcr.io/tempoxyz/tempo:latest',
-      log: log_,
-      ...args
-    } = parameters || {}
-
-    const log = (() => {
-      try {
-        return JSON.parse(log_ as string)
-      } catch {
-        return log_
-      }
-    })()
-    const RUST_LOG = log && typeof log !== 'boolean' ? log : ''
-
-    const name = 'tempo'
-    let container: StartedTestContainer | undefined
-
-    return {
-      _internal: {
-        args,
-      },
-      host: args.host ?? 'localhost',
-      name,
-      port: args.port ?? 8545,
-      async start({ port = args.port }, { emitter }) {
-        const promise = Promise.withResolvers<void>()
-
-        const c = new GenericContainer(image)
-          .withPlatform('linux/x86_64')
-          .withNetworkMode('host')
-          .withExtraHosts([
-            { host: 'host.docker.internal', ipAddress: 'host-gateway' },
-            { host: 'localhost', ipAddress: 'host-gateway' },
-          ])
-          .withName(containerName)
-          .withEnvironment({ RUST_LOG })
-          .withCommand(command({ ...args, port }))
-          .withWaitStrategy(Wait.forLogMessage(/RPC HTTP server started/))
-          .withLogConsumer((stream) => {
-            stream.on('data', (data) => {
-              const message = data.toString()
-              emitter.emit('message', message)
-              emitter.emit('stdout', message)
-              if (log) console.log(message)
-              if (message.includes('shutting down'))
-                promise.reject(new Error(`Failed to start: ${message}`))
-            })
-            stream.on('error', (error) => {
-              if (log) console.error(error.message)
-              emitter.emit('message', error.message)
-              emitter.emit('stderr', error.message)
-              promise.reject(new Error(`Failed to start: ${error.message}`))
-            })
-          })
-          .withStartupTimeout(10_000)
-
-        c.start()
-          .then((c) => {
-            container = c
-            promise.resolve()
-          })
-          .catch(promise.reject)
-
-        return promise.promise
-      },
-      async stop() {
-        if (!container) return
-        await container.stop()
-        container = undefined
-      },
-    }
-  },
-)
-
-export declare namespace tempoDocker {
-  export type Parameters = Omit<tempo.Parameters, 'binary'> & {
-    /**
-     * Name of the container.
-     */
-    containerName?: string | undefined
-    /**
-     * Docker image to use.
-     */
-    image?: string | undefined
-    /**
-     * Host the server will listen on.
-     */
-    host?: string | undefined
-    /**
-     * Port the server will listen on.
-     */
-    port?: number | undefined
-  }
-}

src/testcontainers/Instance.test.ts

@@ -0,0 +1,84 @@
+import getPort from 'get-port'
+import { Instance } from 'prool/testcontainers'
+import { afterEach, expect, test } from 'vitest'
+
+const instances: Instance.Instance[] = []
+
+const port = await getPort()
+
+const defineInstance = (parameters: Instance.tempo.Parameters = {}) => {
+  const instance = Instance.tempo({ port, ...parameters })
+  instances.push(instance)
+  return instance
+}
+
+afterEach(async () => {
+  for (const instance of instances) await instance.stop().catch(() => {})
+})
+
+test('default', async () => {
+  const messages: string[] = []
+  const stdouts: string[] = []
+
+  const instance = defineInstance()
+
+  instance.on('message', (m) => messages.push(m))
+  instance.on('stdout', (m) => stdouts.push(m))
+
+  expect(instance.messages.get()).toMatchInlineSnapshot('[]')
+
+  await instance.start()
+  expect(instance.status).toEqual('started')
+
+  expect(messages.join('')).toBeDefined()
+  expect(stdouts.join('')).toBeDefined()
+  expect(instance.messages.get().join('')).toBeDefined()
+
+  await instance.stop()
+  expect(instance.status).toEqual('stopped')
+
+  expect(messages.join('')).toBeDefined()
+  expect(stdouts.join('')).toBeDefined()
+  expect(instance.messages.get()).toMatchInlineSnapshot('[]')
+})
+
+test('behavior: instance errored (duplicate ports)', async () => {
+  const instance_1 = defineInstance({ port: 8546 })
+  const instance_2 = defineInstance({ port: 8546 })
+
+  await instance_1.start()
+  await expect(() => instance_2.start()).rejects.toThrowError('Failed to start')
+})
+
+test('behavior: start and stop multiple times', async () => {
+  const instance = defineInstance()
+
+  await instance.start()
+  await instance.stop()
+  await instance.start()
+  await instance.stop()
+  await instance.start()
+  await instance.stop()
+  await instance.start()
+  await instance.stop()
+})
+
+test('behavior: can subscribe to stdout', async () => {
+  const messages: string[] = []
+  const instance = defineInstance()
+  instance.on('stdout', (message) => messages.push(message))
+
+  await instance.start()
+  expect(messages.length).toBeGreaterThanOrEqual(1)
+})
+
+test('behavior: can subscribe to stderr', async () => {
+  const messages: string[] = []
+
+  const instance_1 = defineInstance({ port: 8546 })
+  const instance_2 = defineInstance({ port: 8546 })
+
+  await instance_1.start()
+  instance_2.on('stderr', (message) => messages.push(message))
+  await expect(instance_2.start()).rejects.toThrow('Failed to start')
+})

src/testcontainers/Instance.ts

@@ -0,0 +1,117 @@
+import {
+  GenericContainer,
+  type StartedTestContainer,
+  Wait,
+} from 'testcontainers'
+import * as Instance from '../Instance.js'
+import { command, type tempo as core_tempo } from '../instances/tempo.js'
+
+export type { Instance, InstanceOptions } from '../Instance.js'
+
+/**
+ * Defines a Tempo instance.
+ *
+ * @example
+ * ```ts
+ * const instance = Instance.tempo({ port: 8545 })
+ * await instance.start()
+ * // ...
+ * await instance.stop()
+ * ```
+ */
+export const tempo = Instance.define((parameters?: tempo.Parameters) => {
+  const {
+    containerName = `tempo.${crypto.randomUUID()}`,
+    image = 'ghcr.io/tempoxyz/tempo:latest',
+    log: log_,
+    ...args
+  } = parameters || {}
+
+  const log = (() => {
+    try {
+      return JSON.parse(log_ as string)
+    } catch {
+      return log_
+    }
+  })()
+  const RUST_LOG = log && typeof log !== 'boolean' ? log : ''
+
+  const name = 'tempo'
+  let container: StartedTestContainer | undefined
+
+  return {
+    _internal: {
+      args,
+    },
+    host: args.host ?? 'localhost',
+    name,
+    port: args.port ?? 8545,
+    async start({ port = args.port }, { emitter }) {
+      const promise = Promise.withResolvers<void>()
+
+      const c = new GenericContainer(image)
+        .withPlatform('linux/x86_64')
+        .withNetworkMode('host')
+        .withExtraHosts([
+          { host: 'host.docker.internal', ipAddress: 'host-gateway' },
+          { host: 'localhost', ipAddress: 'host-gateway' },
+        ])
+        .withName(containerName)
+        .withEnvironment({ RUST_LOG })
+        .withCommand(command({ ...args, port }))
+        .withWaitStrategy(Wait.forLogMessage(/RPC HTTP server started/))
+        .withLogConsumer((stream) => {
+          stream.on('data', (data) => {
+            const message = data.toString()
+            emitter.emit('message', message)
+            emitter.emit('stdout', message)
+            if (log) console.log(message)
+            if (message.includes('shutting down'))
+              promise.reject(new Error(`Failed to start: ${message}`))
+          })
+          stream.on('error', (error) => {
+            if (log) console.error(error.message)
+            emitter.emit('message', error.message)
+            emitter.emit('stderr', error.message)
+            promise.reject(new Error(`Failed to start: ${error.message}`))
+          })
+        })
+        .withStartupTimeout(10_000)
+
+      c.start()
+        .then((c) => {
+          container = c
+          promise.resolve()
+        })
+        .catch(promise.reject)
+
+      return promise.promise
+    },
+    async stop() {
+      if (!container) return
+      await container.stop()
+      container = undefined
+    },
+  }
+})
+
+export declare namespace tempo {
+  export type Parameters = Omit<core_tempo.Parameters, 'binary'> & {
+    /**
+     * Name of the container.
+     */
+    containerName?: string | undefined
+    /**
+     * Docker image to use.
+     */
+    image?: string | undefined
+    /**
+     * Host the server will listen on.
+     */
+    host?: string | undefined
+    /**
+     * Port the server will listen on.
+     */
+    port?: number | undefined
+  }
+}

src/testcontainers/index.ts

@@ -0,0 +1 @@
+export * as Instance from './Instance.js'

tsconfig.json

@@ -7,7 +7,8 @@
     "moduleResolution": "nodenext",
     "target": "esnext",
     "paths": {
-      "prool": ["./src/index.ts"]
+      "prool": ["./src/index.ts"],
+      "prool/testcontainers": ["./src/testcontainers/index.ts"]
     },
     "types": ["node", "vitest/globals"],