Bugster Hooks - Setup and Cleanup Automation

Hooks allow you to run setup and cleanup code before and after your tests. They are TypeScript/JavaScript functions that execute in your project’s context, enabling you to:

Create test data before tests run
Clean up data after tests complete
Pass dynamic values to your test steps

Hook Structure

Add hooks to your test YAML file:

test.yaml

name: My Test
task: Verify feature works correctly
expected_result: Feature should work

hooks:
  before:
    - helper: createTestUser
      args: ["John", "Doe"]
      as: userId

    - helper: createOrder
      args: ["{{userId}}", "Premium Plan"]
      as: orderId

  after:
    - helper: deleteOrder
      args: ["{{orderId}}"]

    - helper: deleteUser
      args: ["{{userId}}"]

Hook Definition Fields

string

required

Name of the exported function to call.

string

default:".bugster/hooks.ts"

Path to TypeScript file containing the helper function.

array

Array of arguments to pass to the function.

string

Variable name to store the result for later use.

Creating Helper Functions

Default Location

Create a .bugster/hooks.ts file in your project:

.bugster/hooks.ts

export async function createTestUser(
  firstName: string,
  lastName: string,
): Promise<string> {
  // Create user via API or database
  const response = await fetch("https://api.example.com/users", {
    method: "POST",
    body: JSON.stringify({ firstName, lastName }),
  });
  const user = await response.json();
  return user.id; // This becomes available as {{userId}}
}

export async function deleteUser(userId: string): Promise<void> {
  await fetch(`https://api.example.com/users/${userId}`, {
    method: "DELETE",
  });
}

Custom File Locations

You can specify helpers from any TypeScript file in your project:

hooks:
  before:
    - helper: getStoreBySlug
      file_path: apps/e2e/helpers/stores.ts
      args: ["acme-electronics"]
      as: storeId

    - helper: createProductWithParams
      file_path: apps/e2e/helpers/products.ts
      args: ["{{productName}}", "{{price}}", "{{storeId}}"]
      as: productId

Template Variables

Use {{variableName}} to reference values from previous hooks:

Simple Access

- helper: createOrder
  args: ["{{userId}}", 100]
  as: orderId

Nested Object Access

- helper: getShippingAddress
  args: ["{{customerId}}"]
  as: address

- helper: createShipment
  args: ["{{address.zipCode}}", "{{address.country}}"]

Array Access

- helper: getAvailableCoupons
  as: coupons

- helper: applyCoupon
  args: ["{{coupons[0].code}}"]

Passing Hook Data to Tests

Hook results are passed to the test as hook_context. Reference them in your test steps using {{data.variableName}}:

name: Create and verify product
hooks:
  before:
    - helper: generateProductName
      as: productName
task: Create a product named {{data.productName}} and verify it appears in the catalog
expected_result: Product {{data.productName}} should be visible in the products table

Execution Behavior

Before Hooks

Before hooks run sequentially before test execution. If any before hook fails, the test fails with the hook error. Results are stored in context for subsequent hooks.

After Hooks

After hooks run after test completion, regardless of test result. Failures are logged but don’t affect the test result. Use after hooks for cleanup operations.

Complete Example

test.yaml

name: Customer applies discount coupon to cart
page: /checkout

hooks:
  before:
    # Get store data
    - helper: getStoreBySlug
      file_path: apps/e2e/helpers/stores.ts
      args: ["acme-electronics"]
      as: storeId

    # Get related entities (using previous result)
    - helper: getDefaultCategoryByStoreId
      file_path: apps/e2e/helpers/categories.ts
      args: ["{{storeId}}"]
      as: category

    - helper: getPaymentMethodByStoreName
      file_path: apps/e2e/helpers/payments.ts
      args: ["acme-electronics"]
      as: paymentMethod

    # Create test data
    - helper: createProductByApi
      file_path: apps/e2e/helpers/products.ts
      args:
        [
          "{{productName}}",
          "{{category}}",
          "{{paymentMethod.id}}",
          "{{storeId}}",
        ]
      as: productId

    - helper: createCustomerWithParams
      file_path: apps/e2e/helpers/customers.ts
      args: ["{{email}}", "{{firstName}}", "{{storeId}}"]
      as: customerId

  after:
    # Clean up in reverse order
    - helper: removeCartItemsByApi
      file_path: apps/e2e/helpers/cart.ts
      args: ["{{customerId}}", "{{cartId}}"]

    - helper: deleteProductByApi
      file_path: apps/e2e/helpers/products.ts
      args: ["{{productId}}", "{{storeId}}"]

task: Verify customer can apply discount coupon to cart with existing product
steps:
  - Login as test.user@example.com with password SecurePass123!
  - Select store Acme Electronics
  - Navigate to Products section
  - Search for the created product by name
  - Click on product card to open details
  - Click Add to Cart button
  - Navigate to Checkout
  - Enter coupon code in discount field
  - Click Apply button
expected_result: Discount appears in cart summary with updated total

Requirements

Node.js must be installed for hooks to run. TypeScript helpers require tsx which is installed automatically via npx.

For path aliases in tsconfig.json, install tsconfig-paths:

npm install -D tsconfig-paths

Troubleshooting

Hooks file not found

Create .bugster/hooks.ts in your project root or specify the correct file_path for each hook.

Cannot find module

If you’re using path aliases in your tsconfig.json, install tsconfig-paths:

npm install -D tsconfig-paths

Hook returned empty output

Ensure your helper function returns a value. Check that you’re returning the correct data type.

Hook failed with error

Check your helper function for errors. Verify that any external APIs or databases are accessible.

GETTING STARTED

GUIDES

USING THE CLI

HOSTING AND CI/CD

Integrate Hooks

Hook Structure

Hook Definition Fields

Creating Helper Functions

Default Location

Custom File Locations

Template Variables

Simple Access

Nested Object Access

Array Access

Passing Hook Data to Tests

Execution Behavior

Before Hooks

After Hooks

Complete Example

Requirements

Troubleshooting

​Hook Structure

​Hook Definition Fields

​Creating Helper Functions

​Default Location

​Custom File Locations

​Template Variables

​Simple Access

​Nested Object Access

​Array Access

​Passing Hook Data to Tests

​Execution Behavior

​Before Hooks

​After Hooks

​Complete Example

​Requirements

​Troubleshooting

Hook Structure

Hook Definition Fields

Creating Helper Functions

Default Location

Custom File Locations

Template Variables

Simple Access

Nested Object Access

Array Access

Passing Hook Data to Tests

Execution Behavior

Before Hooks

After Hooks

Complete Example

Requirements

Troubleshooting