Hooks - Autosana

Hooks serve as a bridge between your backend or server-side scripts and the Autosana testing environment. They allow you to communicate data, set the state of the app, set the state of a user, etc. They are short programs that run in sandboxed environments during the testing process. They can be added to suites and flows, and any output from them (print statements, console.log, echo) is visible to the agent. A few common examples:

Resetting a user’s onboarding in the backend via JS code
Generating a random email to be used by the Autosana agent via Python code
Returning a magic link or OTP code from your server for Autosana to use in the flow via a cURL request
Mocking audio or video input by hitting an endpoint on your server via TypeScript code

Possibilities are endless and usually the more hooks the better, as it adds a level of determinism to the state of the test! Execution Positions There are three hook execution positions:

Setup Hooks: Run before suites or flows start. Great for providing context.
Runtime Hooks: Run as an action during the flow — added directly into flow instructions, allows real-time backend interaction during testing
Teardown Hooks: Run at the very end of suites and flows. Helpful to clean up testing states

Hook Types

Hooks allow you to configure your test environment in three ways:

Scripts: Python, JavaScript, TypeScript, or Bash scripts that run server-side
cURL Requests: Backend API calls for simple HTTP requests
App Launch Configuration: Configure how your mobile app launches (feature flags, environment settings) - mobile only

Scripts

Server-side scripts that execute in a secure sandbox environment. Choose from Python, JavaScript, TypeScript, or Bash depending on your needs.

If your hook calls a firewalled API, see Network allowlist for the IPs to allow.

Scripts run in a sandboxed environment and cannot use external libraries. Use only built-in/standard libraries (e.g., urllib instead of requests for Python, built-in fetch for JavaScript/TypeScript).

Because hook sandboxes are created from snapshots, pseudo-random generators can repeat values across runs. Avoid Math.random() in JavaScript/TypeScript and unseeded random in Python when generating emails, usernames, IDs, or other unique test data.

Common use cases:

Complex multi-step API operations
Data processing and transformation
Conditional logic based on API responses
Generating dynamic test data
Chaining multiple API calls with error handling

Generating Random Values

Use cryptographically secure randomness from the language standard library when generating unique test data. JavaScript / TypeScript:

const crypto = require('crypto');

const suffix = crypto.randomInt(1, 100000001);
const email = `test-${suffix}@example.com`;
const uniqueId = crypto.randomUUID();

console.log(email);

Python:

import secrets
import string
import uuid

suffix = ''.join(secrets.choice(string.ascii_lowercase) for _ in range(8))
email = f"test-{suffix}@example.com"
unique_id = str(uuid.uuid4())

print(email)

If you must use Python’s random module, seed it from OS entropy at the top of your script:

import os
import random

random.seed(os.urandom(32))

Export a freshly generated value rather than only printing it, or the flow cannot be cached. See Hooks and Run Caching.

cURL Requests

Backend API calls that execute before (setup) or after (teardown) a flow runs. Best for simple, single HTTP requests. Common use cases:

Create test user accounts via your API
Reset database state between flows
Generate auth tokens or session data
Configure backend feature flags
Clean up test data after flows complete

App Launch Configuration (Mobile Only)

Configure values that are passed to your mobile app when it launches. These values are available to your app code as environment variables (iOS) or intent extras (Android).

App Launch Configuration is only available for mobile apps (iOS and Android). For web testing, use Scripts or cURL Requests to configure your test environment.

Common use cases:

Override feature flag values for specific test scenarios
Set test environment parameters (staging vs. production mode)
Configure API timeouts or retry behavior
Enable debug modes or verbose logging
Set experiment variants for A/B testing

Creating a Hook

Navigate to Hooks in the sidebar
Click Create Hook
Enter a hook name (e.g., “Create Test User” or “Generate Auth Token”)
Select hook type:
- Python: For complex logic and data processing
- JavaScript: For Node.js-based operations
- TypeScript: For type-safe Node.js operations
- Bash: For shell script operations
- cURL Request: For simple HTTP API calls
- App Launch Configuration: For mobile app settings (mobile only)
Enter your script or configuration:

For Python:

import urllib.request
import json
import os

data = json.dumps({
    "email": os.environ.get('TEST_EMAIL'),
    "password": os.environ.get('TEST_PASSWORD')
}).encode('utf-8')

req = urllib.request.Request(
    f"{os.environ.get('API_URL')}/auth/login",
    data=data,
    headers={'Content-Type': 'application/json'}
)

with urllib.request.urlopen(req) as response:
    result = json.loads(response.read().decode('utf-8'))

print(f"Logged in as user: {result['userId']}")

# Export token for subsequent hooks
with open('/tmp/autosana.env', 'w') as f:
    f.write(f"AUTH_TOKEN={result['token']}\n")

For JavaScript:

const response = await fetch(`${process.env.API_URL}/auth/login`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    email: process.env.TEST_EMAIL,
    password: process.env.TEST_PASSWORD
  })
});

const data = await response.json();
console.log(`Logged in as user: ${data.userId}`);

// Export token for subsequent hooks
const fs = require('fs');
fs.writeFileSync('/tmp/autosana.env', `AUTH_TOKEN=${data.token}\n`);

For TypeScript:

const response = await fetch(`${process.env.API_URL}/auth/login`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    email: process.env.TEST_EMAIL,
    password: process.env.TEST_PASSWORD
  })
});

interface LoginResponse {
  token: string;
  userId: string;
}

const data: LoginResponse = await response.json();
console.log(`Logged in as user: ${data.userId}`);

// Export token for subsequent hooks
const fs = require('fs');
fs.writeFileSync('/tmp/autosana.env', `AUTH_TOKEN=${data.token}\n`);

For Bash:

RESPONSE=$(curl -s -X POST "${API_URL}/auth/login" \
  -H "Content-Type: application/json" \
  -d "{\"email\":\"${TEST_EMAIL}\",\"password\":\"${TEST_PASSWORD}\"}")

TOKEN=$(echo $RESPONSE | jq -r '.token')
USER_ID=$(echo $RESPONSE | jq -r '.userId')

echo "Logged in as user: $USER_ID"

# Export token for subsequent hooks (append with >>)
echo "AUTH_TOKEN=$TOKEN" >> /tmp/autosana.env

For cURL Requests:

curl -X POST https://api.example.com/users \
  -H "Content-Type: application/json" \
  -d '{"email":"test@example.com","password":"TestPass123"}'

For App Launch Configuration:

{
  "testEnvironment": "staging",
  "featureFlags": {
    "newCheckoutFlow": "enabled",
    "darkMode": true
  },
  "apiTimeout": 30
}

Click Create Hook

Any output from your hooks (print statements, console.log, echo) is passed to the agent as additional context. Use this to provide helpful information about what the hook did!

Testing Hooks

Before attaching hooks to flows, you can test them to verify they work correctly. Dashboard tests use your signed-in session. You do not need to create or paste an Autosana API key.

Open the hook you want to test
Click the Test Hook button
The hook will execute with a 1-minute timeout
View the output to verify success or debug issues

What to check:

Script executes without errors
API calls return expected responses
Environment variables are being read correctly
Exported values (if any) are formatted correctly

Always test hooks independently before attaching them to flows. This helps isolate issues and speeds up debugging.

Using Hooks

Setup & Teardown Hooks

Attaching Setup & Teardown Hooks

Create a new suite or flow or click Edit on an existing one
Expand the Advanced section
Expand the Setup Hooks or Teardown Hooks section
Click the Add a setup hook… or Add a teardown hook… button
Select the hook you want to attach

Hooks attached to a suite are also shown read-only when you expand the suite on the Flows page, so you can see what runs before and after the suite without opening the editor.

Runtime Hooks

You can execute hooks as actions during flow execution by using the syntax ${hooks:Hook Name} in the flow instructions. Example:

Tap the login button, then ${hooks:Create Test User}, then verify the user appears

When the agent encounters ${hooks:Hook Name}, it will:

Look up the hook by name
Execute the hook script
Continue with the rest of the action

This is useful for:

Creating data mid-flow (e.g., “add 5 items to cart, then ${hooks:Create Dummy Discount Code}”)
Triggering backend events at specific points
Resetting state between actions

Runtime Hooks execute synchronously - the flow waits for the hook to complete before continuing.

Execution Order

Setup Hooks execute (if configured)
Flow runs on app start
Agent runs actions and any Runtime Hooks (if configured)
Flow run stops
Teardown Hooks execute (if configured)

Steps 1 and 2 overlap when a setup hook is an App Launch Configuration — the app starts at that hook’s position.

Environment Variables in Hooks

For cURL Requests

Reference environment variables using ${env:VARIABLE_NAME} syntax:

curl -X POST ${env:API_URL}/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"${env:TEST_EMAIL}","password":"${env:TEST_PASSWORD}"}'

Environment variables (in Settings → Environments):

API_URL = https://staging-api.example.com
TEST_EMAIL = test@staging.com
TEST_PASSWORD = SecurePass123

Executed command:

curl -X POST https://staging-api.example.com/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"test@staging.com","password":"SecurePass123"}'

For Scripts (Python, JavaScript, TypeScript, Bash)

Environment variables are automatically injected into the script environment. Access them using your language’s standard method: Python:

import os

api_url = os.environ.get('API_URL')
test_email = os.getenv('TEST_EMAIL')

JavaScript / TypeScript:

const apiUrl = process.env.API_URL;
const testEmail = process.env.TEST_EMAIL;

Bash:

echo $API_URL
echo ${TEST_EMAIL}

Learn more about environment variables →

Click Insert Environment Variable when creating/editing a hook to browse and select from your available environment variables.

Hooks can pass data to subsequent hooks in the same suite. This is useful for scenarios like:

Generating an auth token in a setup hook and using it in a runtime hook
Creating a test user and passing the user ID to a teardown hook for cleanup
Sharing credentials across multiple flows in a suite

How It Works

In your hook, write values to /tmp/autosana.env in KEY=VALUE format
Subsequent hooks can access these values as environment variables
Values persist for all subsequent hooks in the suite (across all flows)

Key Naming Rules

When exporting values, keys must follow these rules:

Rule	Valid	Invalid
Alphanumeric + underscore only	`AUTH_TOKEN`, `API_KEY`, `user_id`	`API-KEY`, `user.id`
Cannot start with a number	`TOKEN_123`, `_INTERNAL`	`123_TOKEN`, `1ST_KEY`

Example: Passing a Token Between Hooks

Setup Hook (Python) - Creates token:

import urllib.request
import json
import os

data = json.dumps({
    "email": "test@example.com",
    "password": "secret"
}).encode('utf-8')

req = urllib.request.Request(
    f"{os.environ.get('API_URL')}/auth/login",
    data=data,
    headers={'Content-Type': 'application/json'}
)

with urllib.request.urlopen(req) as response:
    result = json.loads(response.read().decode('utf-8'))

token = result['token']
user_id = result['userId']

# Export for subsequent hooks
with open('/tmp/autosana.env', 'w') as f:
    f.write(f"AUTH_TOKEN={token}\n")
    f.write(f"TEST_USER_ID={user_id}\n")

print(f"Created session for user {user_id}")

Runtime Hook (cURL) - Uses the token:

curl -X POST ${env:API_URL}/cart/add \
  -H "Authorization: Bearer ${env:AUTH_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"productId": "12345", "quantity": 1}'

Teardown Hook (Python) - Cleans up:

import urllib.request
import os

# Access values exported by setup hook
token = os.environ.get('AUTH_TOKEN')
user_id = os.environ.get('TEST_USER_ID')

# Clean up test user
req = urllib.request.Request(
    f"{os.environ.get('API_URL')}/users/{user_id}",
    method='DELETE',
    headers={'Authorization': f'Bearer {token}'}
)

with urllib.request.urlopen(req) as response:
    pass  # Just need to execute the request

print(f"Cleaned up user {user_id}")

Important Notes

Scripts can read and write exported values
cURL hooks can only read exported values (they cannot write to /tmp/autosana.env)
If multiple hooks export the same key, the latest value wins
Exported values are available to all subsequent hooks in the suite (across all flows)
Exported values are also available to subsequent flows in the suite via ${env:KEY}
The agent can also retrieve exported values directly by name using Get Variable

Hook exports are part of Autosana’s runtime variable system. For a complete overview of how variables work across hooks, flows, and suites, see Variables.

Hooks and Run Caching

Run Caching speeds up a flow by replaying what a previous passing run did, instead of working it out again. Whether that replay is possible depends on how your hook passes values to the flow. If your hook makes a new value every run — a phone number, a test account, a booking reference — Autosana has to learn that the value is meant to change. Until it does, those runs skip the cache and run at full speed. They still pass or fail correctly; they are just slower.

Export the Values Your Flow Uses

Do this. Write the value to /tmp/autosana.env under a name, so each run can be given its own:

number = generate_phone_number()

with open('/tmp/autosana.env', 'w') as f:
    f.write(f"TEST_PHONE={number}\n")

Then reference it in your flow instructions as ${env:TEST_PHONE}, or have the agent fetch it with Get Variable. Not this. Printing it is the only record, and there is no name to look it up by:

print(f"Generated phone number: {generate_phone_number()}")

Everything a setup hook prints is part of what identifies the run. If a hook prints a value that is different every time, every run looks different, so none of them can use the cache — even if the flow never uses that value.

Keep printing things. The run log is the quickest way to debug a hook, and once a value is exported, printing it as well costs nothing.

Which Values Autosana Treats as Changing

Autosana does not guess. It compares each exported value against what the same hook exported last time — same flow version, same environment — and treats it as changing only if it actually changed.

What your hook does with the value	What happens
Exports it, and it differs each run	Each run gets its own value
Exports it, and it stays the same (e.g. `API_URL`)	Treated as fixed; caching works normally
Exports it, but it is under 8 characters	Left alone — something as short as `4821` would match text that has nothing to do with it
Only prints it	Cannot be used; the flow misses the cache every run

It takes three passing runs to settle: the first records the value, the second notices it changed and rebuilds the cache, the third can use it. Failed runs do not count. This is tracked per flow version and environment, so editing the flow’s instructions starts the count over.

Flows That Are Never Cached

Two things turn caching off for a flow, whatever your hooks do:

Using the Run Hook action to run a hook partway through the flow
Using the Set Variable action

Setup and teardown hooks do not affect this — only hooks the agent runs as a step.

Hook Examples

cURL Examples

Create User Account

curl -X POST https://api.example.com/users \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${env:ADMIN_TOKEN}" \
  -d '{
    "email": "${env:TEST_EMAIL}",
    "password": "${env:TEST_PASSWORD}",
    "role": "tester"
  }'

Reset Database

curl -X POST https://api.example.com/test/reset \
  -H "Authorization: Bearer ${env:ADMIN_TOKEN}" \
  -d '{"scope": "test_data"}'

Generate Auth Token

curl -X POST https://api.example.com/auth/token \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "${env:CLIENT_ID}",
    "client_secret": "${env:CLIENT_SECRET}"
  }'

Delete Test Data (Teardown)

curl -X DELETE https://api.example.com/users/${env:TEST_USER_ID} \
  -H "Authorization: Bearer ${env:ADMIN_TOKEN}"

Script Examples

Python: Create User and Export Credentials

import urllib.request
import urllib.error
import json
import os
import secrets
import string

# Generate random email for test user
random_suffix = ''.join(secrets.choice(string.ascii_lowercase) for _ in range(8))
test_email = f"test_{random_suffix}@example.com"

data = json.dumps({
    "email": test_email,
    "password": "TestPass123",
    "role": "tester"
}).encode('utf-8')

req = urllib.request.Request(
    f"{os.environ.get('API_URL')}/users",
    data=data,
    headers={
        'Content-Type': 'application/json',
        'Authorization': f"Bearer {os.environ.get('ADMIN_TOKEN')}"
    }
)

try:
    with urllib.request.urlopen(req) as response:
        user_data = json.loads(response.read().decode('utf-8'))
        print(f"Created test user: {test_email}")

        # Export for use in flow and teardown
        with open('/tmp/autosana.env', 'w') as f:
            f.write(f"TEST_USER_EMAIL={test_email}\n")
            f.write(f"TEST_USER_ID={user_data['id']}\n")
except urllib.error.HTTPError as e:
    raise Exception(f"Failed to create user: {e.read().decode('utf-8')}")

JavaScript: Fetch and Process Data

const response = await fetch(`${process.env.API_URL}/products`, {
  headers: { 'Authorization': `Bearer ${process.env.API_TOKEN}` }
});

const products = await response.json();

// Find a product that's in stock
const availableProduct = products.find(p => p.inStock && p.price < 100);

if (availableProduct) {
  console.log(`Found product: ${availableProduct.name} ($${availableProduct.price})`);

  // Export for use in flow
  const fs = require('fs');
  fs.writeFileSync('/tmp/autosana.env', `TEST_PRODUCT_ID=${availableProduct.id}\n`);
} else {
  throw new Error('No suitable test product found');
}

Bash: Quick API Check

# Check if API is healthy before running tests
HEALTH=$(curl -s -o /dev/null -w "%{http_code}" "${API_URL}/health")

if [ "$HEALTH" != "200" ]; then
  echo "API health check failed with status: $HEALTH"
  exit 1
fi

echo "API is healthy, proceeding with tests"

App Launch Configuration (Mobile Only)

How It Works

App Launch Configuration hooks pass values to your mobile app when it launches. These values are set at app startup and are available throughout your test. This feature is only available for iOS and Android apps.

When It Runs

Setup hooks all run before the app starts — unless one of them is a launch configuration, in which case the app starts at that hook’s position. Put a hook that mints a token or seeds a user above it; hooks below it run against the already-running app. More than one. Each applies at its own position, restarting the app if it is already running. Nested objects merge — setting featureFlags.darkMode keeps the other featureFlags keys — while lists and single values are replaced. A restart keeps device data, not screen state. The app is not reinstalled or reset, so keychain, saved sessions and local databases survive, but the process restarts and the flow begins at your app’s launch screen. In a suite, flows share one session — opened by the suite’s own launch configuration if it declares one. A flow’s launch configuration restarts the app with its values merged over the suite’s; a flow with none keeps what the session already has. With Run flows in parallel, each flow gets its own session and applies the suite’s configuration from scratch.

Dynamic Values (Environment & Build Variables)

Launch configuration JSON supports ${env:VARIABLE_NAME} placeholders, resolved when the hook runs — so a placeholder sees values exported by setup hooks above it, as well as your environment variables and build variables passed via CI (the variables input on the GitHub Action / upload API). This lets you drive launch configuration dynamically — for example, passing an Expo Updates channel from CI:

{
  "EXPO_CHANNEL": "${env:E2E_CHANNEL}"
}

The resolved value is delivered to your app as an iOS environment variable / Android intent extra (see below). Your app is responsible for acting on it — e.g. an Expo app must read the value and call Updates.setUpdateURLAndRequestHeadersOverride(...) followed by Updates.reloadAsync() to switch channels at runtime. If a referenced variable is not set — or is set to an empty or whitespace-only value — the run stops with an error naming it, rather than starting your app with a literal ${env:...} string.

Accessing Values in Your App

iOS (Swift):

// Access simple values (converted to strings)
let environment = ProcessInfo.processInfo.environment
let testEnv = environment["testEnvironment"] // "staging"
let apiTimeout = environment["apiTimeout"] // "30" (as string)

// Nested objects are JSON strings - parse them
if let flagsJSON = environment["featureFlags"],
   let flagsData = flagsJSON.data(using: .utf8) {
    do {
        if let flags = try JSONSerialization.jsonObject(with: flagsData) as? [String: Any] {
            let darkMode = flags["darkMode"] as? Bool // true
            let checkoutFlow = flags["newCheckoutFlow"] as? String // "enabled"
        }
    } catch {
        print("Failed to parse feature flags: \(error)")
    }
}

Android (Kotlin):

import org.json.JSONObject

// Access simple values (type-aware)
val testEnv = intent.extras?.getString("testEnvironment") // "staging"
val apiTimeout = intent.extras?.getInt("apiTimeout") // 30 (as int)

// Nested objects are JSON strings - parse them
val flagsJSON = intent.extras?.getString("featureFlags")
if (flagsJSON != null) {
    try {
        val flags = JSONObject(flagsJSON)
        val darkMode = flags.getBoolean("darkMode") // true
        val checkoutFlow = flags.getString("newCheckoutFlow") // "enabled"
    } catch (e: Exception) {
        Log.e("LaunchArgs", "Failed to parse feature flags", e)
    }
}

React Native:

import { NativeModules, Platform } from "react-native";

// iOS: values are set as environment variables (available via native bridge)
// Android: values are passed as intent extras
const launchArgs = Platform.OS === "ios"
  ? NativeModules.ProcessInfo?.environment
  : NativeModules.IntentExtras?.getExtras();

// Simple values
console.log(launchArgs.testEnvironment); // "staging"
console.log(launchArgs.apiTimeout); // "30" (string on iOS, number on Android)

// Nested objects come as JSON strings - parse them
if (launchArgs.featureFlags) {
    const flags = JSON.parse(launchArgs.featureFlags);
    console.log(flags.darkMode); // true
    console.log(flags.newCheckoutFlow); // "enabled"
}

On iOS, launch configuration values are set as environment variables and accessed via ProcessInfo.processInfo.environment. On Android, they are passed as intent extras and accessed via intent.extras. See the platform-specific examples above for details.

Launch Configuration Examples

Override Feature Flags

{
  "featureFlags": {
    "newCheckoutFlow": "treatment_a",
    "paymentMethodV2": "enabled",
    "showPromotion": false
  }
}

Set Environment and Timeouts

{
  "testEnvironment": "staging",
  "apiBaseUrl": "https://staging-api.example.com",
  "requestTimeout": 30,
  "retryAttempts": 3
}

A/B Testing Configuration

{
  "experiments": {
    "checkoutExperiment": "variant_b",
    "pricingExperiment": "control"
  },
  "userId": "test_user_123"
}

Debug Mode Settings

{
  "enableDebugMode": true,
  "logLevel": "verbose",
  "showPerformanceMetrics": true,
  "mockPaymentProvider": true
}

When to Use Each Hook Type

Use Case	Recommended Hook Type
Simple single API call	cURL
Multiple API calls with logic	Python, JavaScript, or TypeScript
Shell operations, piping commands	Bash
Configure app at startup	App Launch Configuration
Need error handling and retries	Python, JavaScript, or TypeScript
Parse and transform API responses	Python, JavaScript, or TypeScript

Setup Hooks & Agent Context

Pro Tip: When a hook produces output (via print statements, console.log, or echo), the agent automatically receives this data as additional context and can use it during flow execution. Example setup hook:

import urllib.request
import json
import os

data = json.dumps({
    "email": os.environ.get('TEST_EMAIL'),
    "password": os.environ.get('TEST_PASSWORD')
}).encode('utf-8')

req = urllib.request.Request(
    f"{os.environ.get('API_URL')}/auth/login",
    data=data,
    headers={'Content-Type': 'application/json'}
)

with urllib.request.urlopen(req) as response:
    result = json.loads(response.read().decode('utf-8'))

# This output is passed to the agent
print(f"Logged in as: {result['email']}")
print(f"User role: {result['role']}")
print(f"Account created: {result['createdAt']}")

The agent receives this output and can reference it if needed during the flow execution.

A setup hook’s output also feeds into the run cache, so printing a value that changes every run — a timestamp, a fresh ID — costs you the cache. See Hooks and Run Caching.

Timeouts

Hooks have different timeout limits depending on the context:

Context	Timeout
Testing hooks (via Test button)	1 minute
Flow execution (setup, runtime, teardown)	5 minutes

If a hook exceeds its timeout, it will be terminated and marked as failed.

Keep hooks focused and fast. If you have long-running operations, consider breaking them into multiple hooks or optimizing your API calls.

Best Practices

Use Descriptive NamesName hooks after what they do: “Create Premium Test User” instead of “Hook 1”

Store Secrets in Environment VariablesNever hardcode API keys or passwords in hooks. Use environment variables like ${env:API_KEY}.

Test Hooks IndependentlyUse the Test button to verify your hooks work correctly before attaching them to flows.

Use Teardown Hooks for CleanupAlways clean up test data created by setup hooks to avoid polluting your backend. For concurrent runs, follow Making Suites, Parallelizable, Isolated, and Repeatable so one session cannot change or delete another session’s data.

Keep Hooks SimpleEach hook should do one thing. Create separate hooks for different setup tasks.

Use Scripts for Complex LogicWhen you need conditionals, loops, error handling, or data processing, use Python/JavaScript instead of complex cURL commands.

Export Only What You NeedWhen sharing data between hooks, only export the values that subsequent hooks actually need.

Add Helpful Print StatementsOutput from your hooks is passed to the agent. Add print statements to provide context about what happened.

Hooks vs Suite Auth Instructions

Feature	Hooks	Suite Auth Instructions
Type	Scripts, cURL, or Launch args	Natural language instructions
Purpose	Setup/cleanup backend state	Navigate app to starting point
Execution	Before/after each flow	Once at suite start
Reusability	Can be used across many flows	Specific to one suite

Use hooks when: You need to configure backend state, create test data, or call APIs Use suite auth instructions when: You need to start the suite from a specific state (e.g., logged in with a certain test account)

Troubleshooting

Script Issues

Script times out

Hooks have a 5-minute timeout during flow execution (1 minute when testing)
Break long operations into multiple hooks
Check for infinite loops or slow API endpoints

Environment variable not found

Verify the variable exists in Settings → Environments
Check spelling and case (variable names are case-sensitive)
For scripts, use the correct access method for your language

Random values are the same every run

Hook sandboxes are created from snapshots, so pseudo-random generators may repeat their seed across runs
In JavaScript/TypeScript, use Node’s built-in crypto module (crypto.randomInt, crypto.randomUUID) instead of Math.random()
In Python, prefer secrets or uuid; if you must use random, call random.seed(os.urandom(32)) before generating values

Exported values not available in next hook

Verify you wrote to /tmp/autosana.env (exact path)
Check key naming rules (alphanumeric + underscore, can’t start with number)
Ensure the format is KEY=VALUE with one per line

cURL Request Issues

Hook fails to execute

Verify the curl command works in your terminal first
Check that environment variables are defined
Ensure API endpoints are accessible from Autosana’s infrastructure

Environment variables not replacing

Syntax must be ${env:VARIABLE_NAME} (not {{VARIABLE_NAME}} or $VARIABLE_NAME)
Variable names are case-sensitive
Variables must exist in Settings → Environments

App Launch Configuration Issues

Configuration not appearing in app

Verify JSON is valid (use a JSON validator)
Check you’re accessing values correctly for your platform (ProcessInfo for iOS, intent.extras for Android)
Ensure the hook is attached as a setup hook (launch configuration doesn’t work in teardown)

Values have wrong type

On iOS, all values become strings (including numbers and booleans)
On Android, primitives keep their types (int, float, boolean, string)
Nested objects are JSON-serialized as strings on both platforms
Use the examples in this guide to parse nested structures correctly

Hook can’t read value from previous hook

Ensure the previous hook successfully wrote to /tmp/autosana.env
Check that the previous hook completed without errors
Verify the key name matches exactly (case-sensitive)

Invalid key name warning

Keys must contain only letters, numbers, and underscores
Keys cannot start with a number
Examples: AUTH_TOKEN ✓, 123_KEY ✗, API-KEY ✗

Managing Hooks via API

Hooks can be created, updated, and deleted programmatically via the Hooks API. Useful for syncing hook definitions from your repo, bulk-importing from another system, or wiring up custom tooling. Hooks can also live as script files in your repository and be referenced from code-managed flows — see Hooks as files.

​Hook Types

​Scripts

​Generating Random Values

​cURL Requests

​App Launch Configuration (Mobile Only)

​Creating a Hook

​For Python:

​For JavaScript:

​For TypeScript:

​For Bash:

​For cURL Requests:

​For App Launch Configuration:

​Testing Hooks

​Using Hooks

​Setup & Teardown Hooks

​Runtime Hooks

​Execution Order

​Environment Variables in Hooks

​For cURL Requests

​For Scripts (Python, JavaScript, TypeScript, Bash)

​Sharing Data Between Hooks

​How It Works

​Key Naming Rules

​Example: Passing a Token Between Hooks

​Important Notes

​Hooks and Run Caching

​Export the Values Your Flow Uses

​Which Values Autosana Treats as Changing

​Flows That Are Never Cached

​Hook Examples

​cURL Examples

​Create User Account

​Reset Database

​Generate Auth Token

​Delete Test Data (Teardown)

​Script Examples

​Python: Create User and Export Credentials

​JavaScript: Fetch and Process Data

​Bash: Quick API Check

​App Launch Configuration (Mobile Only)

​How It Works

​When It Runs

​Dynamic Values (Environment & Build Variables)

​Accessing Values in Your App

​Launch Configuration Examples

​Override Feature Flags

​Set Environment and Timeouts

​A/B Testing Configuration

​Debug Mode Settings

​When to Use Each Hook Type

​Setup Hooks & Agent Context

​Timeouts

​Best Practices

​Hooks vs Suite Auth Instructions

​Troubleshooting

​Script Issues

​cURL Request Issues

​App Launch Configuration Issues

​Data Sharing Issues

​Managing Hooks via API

​Next Steps

Hook Types

Scripts

Generating Random Values

cURL Requests

App Launch Configuration (Mobile Only)

Creating a Hook

For Python:

For JavaScript:

For TypeScript:

For Bash:

For cURL Requests:

For App Launch Configuration:

Testing Hooks

Using Hooks

Setup & Teardown Hooks

Runtime Hooks

Execution Order

Environment Variables in Hooks

For cURL Requests

For Scripts (Python, JavaScript, TypeScript, Bash)

Sharing Data Between Hooks

How It Works

Key Naming Rules

Example: Passing a Token Between Hooks

Important Notes

Hooks and Run Caching

Export the Values Your Flow Uses

Which Values Autosana Treats as Changing

Flows That Are Never Cached

Hook Examples

cURL Examples

Create User Account

Reset Database

Generate Auth Token

Delete Test Data (Teardown)

Script Examples

Python: Create User and Export Credentials

JavaScript: Fetch and Process Data

Bash: Quick API Check

App Launch Configuration (Mobile Only)

How It Works

When It Runs

Dynamic Values (Environment & Build Variables)

Accessing Values in Your App

Launch Configuration Examples

Override Feature Flags

Set Environment and Timeouts

A/B Testing Configuration

Debug Mode Settings

When to Use Each Hook Type

Setup Hooks & Agent Context

Timeouts

Best Practices

Hooks vs Suite Auth Instructions

Troubleshooting

Script Issues

cURL Request Issues

App Launch Configuration Issues

Data Sharing Issues

Managing Hooks via API

Next Steps