feat: add stepTimeout option for quickpickle

Author: dnotes

.changeset/rude-houses-drop.md

@@ -0,0 +1,5 @@
+---
+"quickpickle": minor
+---
+
+feat: added stepTimeout option for quickpickle

packages/main/README.md

@@ -170,11 +170,12 @@ Also add the configuration to get the feature files, step definitions, world fil
 
 ```ts
 // vite.config.ts
-import { quickpickle } from 'quickpickle';
+import { quickpickle, type QuickPickleConfigSetting } from './src';
+const qpOptions:QuickPickleConfigSetting = {}
 
 export default {
   plugins: [
-    quickpickle() // <-- Add the quickpickle plugin
+    quickpickle(qpOptions) // <-- Add the quickpickle plugin
   ],
   test: {
     include : [
@@ -193,30 +194,100 @@ different browser environments, different world constructors, etc.
 ```ts
 // vitest.workspace.ts
 import { defineWorkspace } from 'vitest/config';
+import type { QuickPickleConfigSetting } from 'quickpickle';
+
+const options1:QuickPickleConfigSetting = {} // some settings for e.g. e2e tests
+const options2:QuickPickleConfigSetting = {} // other settings for e.g. component tests
 
 export default defineWorkspace([
   { // configuration for feature files testing the application
     extends: './vite.config.ts',
     test: {
-      include : [ 'tests/*.feature' ],
+      name: 'e2e',
+      include: [ 'tests/*.feature' ],
       setupFiles: [ 'tests/tests.steps.ts' ],
+      quickpickle: options1,
     },
   },
   { // a second configuration for feature files testing components
     extends: './vite.config.ts',
     test: {
-      include : [ 'src/lib/*.feature' ],
+      name: 'components',
+      include: [ 'src/lib/*.feature' ],
       setupFiles: [ 'tests/components.steps.ts' ],
+      quickpickle: options2,
     },
   },
   { // configuration for unit tests
     test: {
-      include : [ 'tests/*.test.ts' ],
+      name: 'unit',
+      include: [ 'tests/*.test.ts' ],
     }
   }
 ])
 ```
 
+The QuickPickle configuration options can be seen
+in the [quickpickle defaultConfig object](https://github.com/dnotes/quickpickle/blob/main/packages/main/src/index.ts#L159):
+
+```ts
+export const defaultConfig: QuickPickleConfig = {
+
+  /**
+   * The root directory for the tests to run, from vite or vitest config
+   */
+  root: '',
+
+  /**
+   * The maximum time in ms to wait for a step to complete.
+   */
+  stepTimeout: 3000,
+
+  /**
+   * Tags to mark as todo, using Vitest's `test.todo` implementation.
+   */
+  todoTags: ['@todo','@wip'],
+
+  /**
+   * Tags to skip, using Vitest's `test.skip` implementation.
+   */
+  skipTags: ['@skip'],
+
+  /**
+   * Tags to mark as failing, using Vitest's `test.failing` implementation.
+   */
+  failTags: ['@fails', '@failing'],
+
+  /**
+   * Tags to mark as soft failing, allowing further steps to run until the end of the scenario.
+   */
+  softFailTags: ['@soft', '@softfail'],
+
+  /**
+   * Tags to run in parallel, using Vitest's `test.concurrent` implementation.
+   */
+  concurrentTags: ['@concurrent'],
+
+  /**
+   * Tags to run sequentially, using Vitest's `test.sequential` implementation.
+   */
+  sequentialTags: ['@sequential'],
+
+  /**
+   * Explode tags into multiple tests, e.g. for different browsers.
+   */
+  explodeTags: [],
+
+  /**
+   * The config for the World class. Must be serializable with JSON.stringify.
+   * Not used by the default World class, but may be used by plugins or custom
+   * implementations, like @quickpickle/playwright.
+   */
+  worldConfig: {},
+
+}
+```
+
 ### Step definition file
 
 You'll always need a step definition file, to set up the step defintions and potentially the world
@@ -423,7 +494,9 @@ come to notice:
     isComplete: boolean           // (read only) whether the Scenario is on the last step
     config: QuickPickleConfig                       // (read only) configuration for QuickPickle
     worldConfig: QuickPickleConfig['worldConfig']   // (read only) configuration for the World
-    common: {[key: string]: any}                    // Common data shared across tests --- USE SPARINGLY
+    data: {[key:string]:any}      // Data limited to the current Scenario
+    common: Common                // Common data shared across ALL tests in one Feature file --- USE SPARINGLY
+    projectRoot: string           // (read only) the project root directory
     init: () => Promise<void>                       // function called by QuickPickle when the world is created
     tagsMatch(tags: string[]): string[]|null        // function to check if the Scenario tags match the given tags
   }

packages/main/gherkin-example/example.feature.js

@@ -47,15 +47,27 @@ interface StepDefinitionMatch {
   parameters: any[];
 }
 
+const stackRegex = /\.feature(?:\.md)?:\d+:\d+/
 export function formatStack(text:string, line:string) {
+  if (!text.match(stackRegex)) return text
   let stack = text.split('\n')
-  while(!stack[0]?.match(/\.feature(?:\.md)?:\d+:\d+/)) stack.shift()
-  if (!stack.length) return text
+  while(!stack[0].match(stackRegex)) stack.shift()
   stack[0] = stack[0].replace(/:\d+:\d+$/, `:${line}:1`)
   return stack.join('\n')
 }
 
-export const gherkinStep = async (stepType:"Context"|"Action"|"Outcome", step: string, state: any, line: number, stepIdx:number, explodeIdx?:number, data?:any): Promise<any> => {
+function raceTimeout<T>(work: Promise<T>, ms: number, errorMessage?: string) {
+  let timerId: ReturnType<typeof setTimeout>;
+  const timeoutPromise = new Promise<never>((_, reject) => {
+    timerId = setTimeout(() => reject(new Error(errorMessage)), ms);
+  });
+
+  // make sure to clearTimeout on either success *or* failure
+  const wrapped = work.finally(() => clearTimeout(timerId));
+  return Promise.race([wrapped, timeoutPromise]);
+}
+
+export const gherkinStep = async (stepType:"Context"|"Action"|"Outcome", step: string, state: any, line: number, stepIdx:number, explodeIdx?:number, data?:any):Promise<any> => {
 
   try {
     // Set the state info
@@ -76,31 +88,36 @@ export const gherkinStep = async (stepType:"Context"|"Action"|"Outcome", step: s
       dataType = 'docString'
     }
 
-    await applyHooks('beforeStep', state);
+    const promise = async () => {
 
-    try {
-      const stepDefinitionMatch: StepDefinitionMatch = findStepDefinitionMatch(step, { stepType, dataType });
-      await stepDefinitionMatch.stepDefinition.f(state, ...stepDefinitionMatch.parameters, data);
-    }
-    catch(e:any) {
-      // Add the Cucumber info to the error message
-      e.message = `${step} (#${line})\n${e.message}`
+      await applyHooks('beforeStep', state);
 
-      // Sort out the stack for the Feature file
-      e.stack = formatStack(e.stack, state.info.line)
+      try {
+        const stepDefinitionMatch: StepDefinitionMatch = findStepDefinitionMatch(step, { stepType, dataType });
+        await stepDefinitionMatch.stepDefinition.f(state, ...stepDefinitionMatch.parameters, data);
+      }
+      catch(e:any) {
+        // Add the Cucumber info to the error message
+        e.message = `${step} (#${line})\n${e.message}`
 
-      // Set the flag that this error has been added to the state
-      e.isStepError = true
+        // Sort out the stack for the Feature file
+        e.stack = formatStack(e.stack, state.info.line)
 
-      // Add the error to the state
-      state.info.errors.push(e)
+        // Set the flag that this error has been added to the state
+        e.isStepError = true
+
+        // Add the error to the state
+        state.info.errors.push(e)
+
+        // If not in a soft fail mode, re-throw the error
+        if (state.isComplete || !state.tagsMatch(state.config.softFailTags)) throw e
+      }
+      finally {
+        await applyHooks('afterStep', state);
+      }
 
-      // If not in a soft fail mode, re-throw the error
-      if (state.isComplete || !state.tagsMatch(state.config.softFailTags)) throw e
-    }
-    finally {
-      await applyHooks('afterStep', state);
     }
+    await raceTimeout(promise(), state.config.stepTimeout, `Step timed out after ${state.config.stepTimeout}ms`)
   }
   catch(e:any) {
 
@@ -119,7 +136,7 @@ export const gherkinStep = async (stepType:"Context"|"Action"|"Outcome", step: s
 
     // The After hook is usually run in the rendered file, at the end of the rendered steps.
     // But, if the tests have failed, then it should run here, since the test is halted.
-    await applyHooks('after', state)
+    await raceTimeout(applyHooks('after', state), state.config.stepTimeout, `After hook timed out after ${state.config.stepTimeout}ms`)
 
     // Otherwise throw the error
     throw e
@@ -131,10 +148,12 @@ export const gherkinStep = async (stepType:"Context"|"Action"|"Outcome", step: s
       throw error
     }
   }
+
 };
 
 export type QuickPickleConfigSetting<T = {[key:string]:any}> = Partial<{
   root?:string
+  stepTimeout: number
   todoTags: string|string[]
   skipTags: string|string[]
   failTags: string|string[]
@@ -147,6 +166,7 @@ export type QuickPickleConfigSetting<T = {[key:string]:any}> = Partial<{
 
 export type QuickPickleConfig<T = {[key:string]:any}> = {
   root: string
+  stepTimeout: number
   todoTags: string[]
   skipTags: string[]
   failTags: string[]
@@ -164,6 +184,11 @@ export const defaultConfig: QuickPickleConfig = {
    */
   root: '',
 
+  /**
+   * The maximum time in ms to wait for a step to complete.
+   */
+  stepTimeout: 3000,
+
   /**
    * Tags to mark as todo, using Vitest's `test.todo` implementation.
    */
@@ -204,7 +229,7 @@ export const defaultConfig: QuickPickleConfig = {
    * Not used by the default World class, but may be used by plugins or custom
    * implementations, like @quickpickle/playwright.
    */
-  worldConfig: {}
+  worldConfig: {},
 
 }
 

packages/main/src/index.ts

@@ -30,6 +30,7 @@ export interface QuickPickleWorldInterface {
   worldConfig: QuickPickleConfig['worldConfig']   // (read only) configuration for the World
   data: {[key:string]:any}      // Data limited to the current Scenario
   common: Common                // Common data shared across ALL tests in one Feature file --- USE SPARINGLY
+  projectRoot: string           // (read only) the project root directory
   init: () => Promise<void>                       // function called by QuickPickle when the world is created
   tagsMatch(tags: string[]): string[]|null        // function to check if the Scenario tags match the given tags
 }

packages/main/src/world.ts

@@ -262,3 +262,12 @@ Feature: Basic Test
       Given this step is undefined
       Then error 1 should contain "Given('this step is undefined', async function (world) {"
       And clear error 1
+
+  @soft
+  Rule: Steps should have a timeout
+
+    Example: a test with a step that times out
+      When a step takes too long
+      Then error 1 should contain "a step takes too long"
+      And error 1 should contain "timed out after"
+      And clear error 1

packages/main/tests/test.feature

@@ -111,6 +111,11 @@ When('I push all the numbers {updown}( again)', (world, updown:'up'|'down') => {
   world.numbers = world.numbers.map(n => updown === 'up' ? n+1 : n-1)
 })
 
+// TIMEOUTS
+When('a step takes too long', async function (world) {
+  await new Promise(resolve => setTimeout(resolve, 10000));
+});
+
 // RENDERER
 
 Given("the following feature( file)( is rendered):", (world, feature:DocString) => {