Writing Effective Journeys

Goal-Oriented vs. Click-Specific

This is the single most important principle. Write prompts that describe the goal, not the exact clicks.

• Too specific: "Click the blue button labeled 'Submit' at the bottom of the form, then wait for the modal with class 'success-dialog' to appear." This breaks the moment the button text changes or the modal is redesigned.
• Goal-oriented: "Submit the form and verify that a success confirmation appears." The agent sees the page, finds the submit action, and checks for confirmation — regardless of button color, label, or implementation.

Goal-oriented prompts are resilient to UI changes. When the design team updates button labels, restructures forms, or moves elements around, goal-oriented prompts keep working. Click-specific prompts break every time.

Use click-specific language only when you are intentionally testing a specific UI element — for example, verifying that a particular button exists or that a specific label is correct.

Anatomy of a Good Prompt

A good journey prompt has three parts:

• Context. Who is the user and what are they trying to accomplish? The optional role assigned to the run sets the broad behavioural tone (a UX auditor reads differently than a power user); the journey prompt itself fills in the specifics. Example: "You are a new customer creating your first order."
• Actions. What should the agent do? Describe the steps as goals, not clicks. Example: "Create a new order with at least two line items, apply a discount code, and proceed to checkout."
• Verification. What does success look like? Be explicit. Example: "Success means: the order confirmation page shows an order number, the line items match what was entered, and the discount is reflected in the total."

Here is a complete example:

Create a new invoice for a fictional client. Fill in the client name,
a description, and add two line items with realistic amounts.

Submit the invoice and verify that:
- The invoice appears in the invoice list
- The status shows "Draft"
- The total matches the sum of the line items

Writing Milestones

Write the milestones you expect the agent to reach as numbered steps directly in the prompt. Both the agent and the post-run summarizer use those steps to track progress, so a checkout prompt that lists “1. log in”, “2. add an item”, “3. complete checkout” will surface in the report as “hit step 2, failed step 3” without any extra configuration.

This replaces the older standalone “Checkpoints” list — the prompt is now the single source of truth for what the journey is supposed to do.

Authentication

Most web applications require login. Aiqaramba does not store credentials for you — the journey prompt tells the agent which test account to use, and the agent fills in the form like a person would. A few practical patterns:

• Use a dedicated test account. Spell its email and password out in the prompt, or pass them as run-time variables and reference them via {{ .Vars.<name> }}. The variable approach lets you rotate the password without editing the journey.
• Magic links and email verification. Attach a mailbox to the journey and ask the agent to read the inbox when the flow needs a one-time code or a verification link.
• Start at the login page. Set the journey's entry URL to your app's login page so the agent lands there first and can authenticate before proceeding to the rest of the flow.

Handling Dynamic Content

Modern web apps load content dynamically — pages rendered client-side, content that appears after API calls, elements that animate in. Agents handle most of this automatically, but you can help them with a few practices:

• Mention waiting for pages to load. For client-side rendered apps (React, Next.js, Vue), add a note like "Wait for the page to fully load before interacting." This tells the agent to take a screenshot and verify the page is ready before clicking.
• Use flexible verification language. Instead of "Verify the page shows 'Widget A, Widget B, Widget C'" (which depends on exact data), write "Verify the page shows a product listing with at least one item." This works regardless of what specific data is loaded.
• Ask for screenshots at key moments. Adding "Take a screenshot after the page loads" helps both the agent (it forces a pause to observe) and you (you get visual proof of what the agent saw).

Negative Constraints

Agents are curious by default — they explore what they see. If there are things you do not want the agent to do, say so explicitly:

Test the account settings page. Update the display name and save.

Do NOT:
- Click "Delete Account"
- Change the email address
- Navigate away from the settings section

Negative constraints are especially important for destructive actions (deleting data, canceling subscriptions) and for keeping the agent focused on the specific flow you want to test.

The Iteration Workflow

The first version of a journey prompt is rarely perfect. Expect to iterate two or three times before a journey runs reliably. Here is the process:

• 1. Write the prompt. Start with the goal, keep it simple, include a success condition.
• 2. Run the journey and open the trace view. The step-by-step screenshots and tool calls show exactly what the agent did.
• 3. Watch the recording. See where the agent succeeded and where it got stuck. Read the step-by-step conversation log to understand its reasoning.
• 4. Refine the prompt. If the agent got stuck on a loading screen, add a wait instruction. If it clicked the wrong thing, add a negative constraint. If it skipped a step, make that step more explicit.
• 5. Re-run. Test the updated prompt. Repeat until the journey passes reliably.

Common Mistakes

• Too vague. "Test the app" gives the agent no direction. It will wander randomly. Always specify which flow to test and what success looks like.
• Too many flows in one journey. "Test login, then create an invoice, then set up integrations, then update profile settings" tries to cover too much. If step two fails, you learn nothing about steps three and four. Split into separate journeys.
• Hardcoded CSS selectors. "Click the element with id='btn-submit'" breaks whenever the code changes. Describe the intent instead: "Click the submit button."
• No success condition. Without a clear definition of success, the agent cannot evaluate whether the test passed. Always end with "Success means..." or "Verify that..."
• Real-user credentials in prompts. Use a dedicated test account, never the credentials of a real user. Prefer run-time variables over hardcoding so you can rotate the password without editing every journey that references it.

Examples

Here are some before-and-after examples showing how to improve journey prompts.

Login test

Before: "Test the login page."

After: "Navigate to the login page. Log in with the test account email
(tester@example.com) and password (passed in via the run's variables).
Verify that the dashboard loads and shows at least one navigation item.
Take a screenshot of the dashboard."

Form submission

Before: "Fill in the contact form and submit it."

After: "Fill in the contact form with a realistic name, email, and message.
Submit the form. Verify that a success message appears and the form fields
are cleared. Do not navigate away from the page after submitting."

Multi-step workflow

Before: "Create an invoice and send it."

After: "Create a new invoice: fill in a client name, add two line items
with realistic descriptions and amounts. Save the invoice and verify it
appears in the invoice list with status 'Draft'. Then open the invoice and
click Send. Verify the status changes to 'Sent'.

Success means: the invoice exists in the list with status 'Sent' and the
total matches the sum of the line items."

Resilience test

Before: "Test error handling on the signup form."

After: "Go to the signup page. Try submitting the form without filling in
any fields. Verify that validation errors appear for each required field.
Then fill in only the email with an invalid format (e.g. 'notanemail') and
submit again. Verify that a specific email validation error appears.

Success means: the form shows appropriate error messages for each invalid
or missing field, and does not submit until all fields are valid."