feat: configurable step timeouts (#12)

Author: DonIsaac

lib/index.ts

@@ -1,6 +1,7 @@
 export type { Context, EcosystemSuite } from './test-suite'
 export { TestSuite, TestCase, Step } from './test-suite'
 export * as steps from './steps'
+export type { Maybe } from './types'
 
 // test suite templates
 export { installAndTest } from './install-and-test'

lib/test-suite.ts

@@ -1,5 +1,6 @@
 import deepmerge from 'deepmerge'
 import type { Maybe } from './types'
+import { strict as assert } from 'node:assert'
 
 /**
  * Test suites have similar checks over a bunch of cases. Each case normally
@@ -160,6 +161,13 @@ export interface Step {
      * Current working directory to use when running commands for this step.
      */
     cwd?: string
+    /**
+     * Timeout for this step in milliseconds. If the step takes longer than
+     * this, it fails. By default, no timeout is set.
+     *
+     * @min 1
+     */
+    timeout?: number
     /**
      * Buildkite-specific configuration. These aren't used for other kinds of runners.
      */
@@ -225,4 +233,14 @@ export namespace Step {
 
         return true
     }
+
+    export function validate(step: Step): void {
+        assert(step.run?.length, 'Step must have at least one command')
+        if (step.timeout != null) {
+            assert(
+                step.timeout > 0,
+                `Timeout must be greater than 0, got ${step.timeout}`
+            )
+        }
+    }
 }

src/__snapshots__/shell.test.ts.snap

@@ -0,0 +1,8 @@
+// Bun Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`renderStep respects \`step.timeout\` 1`] = `
+"# Step: echo "hello world"
+timeout --verbose --kill-after=2000 1000 (
+  echo "hello world"
+)"
+`;

src/local.ts

@@ -2,6 +2,7 @@ import assert from 'assert'
 import path from 'path'
 import { Command } from 'commander'
 import {
+    Step,
     TestSuite,
     type Context,
     type EcosystemSuite,
@@ -214,7 +215,8 @@ async function runAllTests({
 
 async function runCase(testCase: TestCase): Promise<number> {
     for (const step of testCase.steps) {
-        const { run, env: stepEnv, cwd, name } = step
+        Step.validate(step)
+        const { run, env: stepEnv, cwd, name, timeout } = step
         const env = Object.assign(
             pick(process.env, inheritEnvVarNames),
             testCase.env,
@@ -226,6 +228,7 @@ async function runCase(testCase: TestCase): Promise<number> {
             stdio: ['pipe', 'inherit', 'inherit'],
             cwd,
             env,
+            timeout,
         })
         for (const cmd of run) {
             child.stdin.write(cmd + '\n')

src/shell.test.ts

@@ -111,5 +111,17 @@ describe(renderStep, () => {
             })
             expect(await result.exited).toBe(0)
         })
+    }) // </ when a basic step is rendered>
+
+    it('respects `step.timeout`', () => {
+        const actual = renderStep(
+            Step.from('echo "hello world"', {
+                timeout: 1000,
+            })
+        )
+        expect(actual).not.toBeEmpty()
+        const rendered = actual.join('\n')
+        expect(rendered).toMatchSnapshot()
+        expect(rendered).toMatch(/timeout.*1000/)
     })
 })

src/shell.ts

@@ -1,5 +1,5 @@
 import assert from 'node:assert'
-import type { Step, TestCase, TestSuite } from '../lib'
+import type { Step, TestCase, TestSuite, Maybe } from '../lib'
 
 /**
  * Render a test suite into a shell script.
@@ -76,7 +76,7 @@ export function renderStep(step: Step): string[] {
 
     const lines = [`# Step: ${name ?? [run[0]]}`]
     if (name) lines.push(`echo '${name.replaceAll("'", "\\'")}'`)
-    lines.push(...subshell(indent(cmds)))
+    lines.push(...withTimeout(step.timeout)(subshell(indent(cmds))))
 
     return lines
 }
@@ -101,3 +101,12 @@ const withDir = (dir: string | undefined) =>
     dir ? wrap(`pushd ${dir}`, 'popd') : reifyLines //wrap('', '')
 /** Runs commands in a subshell */
 const subshell = wrap('(', ')')
+const withTimeout =
+    (timeout: Maybe<number>) =>
+    (lines: string[]): string[] => {
+        if (timeout == null || !lines.length) return lines
+        assert(timeout > 0)
+        assert(lines.length > 0)
+        lines[0] = `timeout --verbose --kill-after=${timeout * 2} ${timeout} ${lines[0]}`
+        return lines
+    }