Lifecycle Hooks

Lifecycle hooks allow you to execute custom logic at specific stages of the testing process. This is essential for managing provider state, such as setting up test data or cleaning up after an operation.

Verification Lifecycle

The Drift engine emits events throughout the execution of a test suite. You can "hook" into these events using the event_handlers table in your Lua script.

Event Name	Best Use Case
`testcase:started`	Global setup (e.g., seeding a database).
`testcase:finished`	Global cleanup after all operations complete.
`operation:started`	Per-test setup (e.g., ensuring a specific record exists).
`operation:prepared`	Modify operation parameters before invocation.
`operation:finished`	Post-test cleanup (e.g., deleting created resources).
`operation:failed`	Handle verification failures or log debugging info.
`http:request`	Modifying headers or bodies immediately before dispatch.

For a comprehensive list of all available events, see the Lua API Reference.

Common patterns

Review the most used patterns.

Data Cleanup (Teardown)

Use the operation:finished hook to reset your environment. This ensures that subsequent tests start with a clean slate.

-- product.lua
["operation:finished"] = function(event, data)
  -- Perform a teardown request to a dev-only endpoint
  local res = http({
    url = "http://localhost:8080/teardown",
    method = "POST",
    body = ""
  })
end

Dynamic Request Modification

If you need to inject a dynamic header (like a custom signature or an evolving token) into every request, use the http:request event.

["http:request"] = function(event, data)
  -- data contains headers, method, and body
  data.headers["x-request-timestamp"] = os.date("!%Y-%m-%dT%H:%M:%SZ")
  
  -- Return the modified data to the engine
  return data
end

Debugging with Lifecycle Data

When a hook isn't behaving as expected, use dbg() to inspect the metadata passed to the handler.

["operation:started"] = function(event, data)
  -- data[2] typically contains the Operation ID
  print("DEBUG: Starting " .. data[2])
  print(dbg(data)) 
end

In this section: