Core Concepts

Before diving into setup guides and API references, it helps to understand the building blocks of Aiqaramba and how they fit together. This page defines every core concept you will encounter and explains the relationships between them.

The Building Blocks

Everything in Aiqaramba is built from these pieces. You do not need all of them to get started, but understanding what each one does will help you make better decisions as you scale your testing.

  • Project. A container for one application you are testing. Everything else — journeys, discoveries, schedules — lives inside a project. Most teams create one project per environment (staging, production) or per application.
  • Journey. A reusable test scenario described in plain language. Instead of writing test code, you write a goal: "Sign up for a new account and verify the welcome page loads." You define a journey once and run it as many times as you want. Each run creates a new agent.
  • Agent. A single test run. When you run a journey, Aiqaramba creates an agent that opens a real browser, follows the journey instructions, takes screenshots at each step, and reports what happened. Agents are ephemeral — you do not create them directly, they are created when a journey runs.
  • Discovery. Autonomous site exploration. You point a discovery at a URL and it sends multiple agents to crawl your application across several phases. They map every page, form, and interaction they find. The result is a complete map of your app plus suggested journeys you can create with one click. See the Site Discovery guide for details.
  • Mailbox. A real email address your tests can read. Create one and any message sent to name@agents.aiqaramba.com is stored against the mailbox. Attach a mailbox to a journey or test run and the agent can read the inbox at any point during the run, useful for magic links, verification codes, and signup confirmations. Mailboxes are read-only: nothing on the platform can send mail. See the Mailboxes guide for details.
  • Role. A testing perspective that shapes how the agent approaches its task. A "Functional QA" role focuses on whether features work correctly. A "UX Auditor" role pays attention to usability issues. A "New User" role simulates someone using the app for the first time. Roles are injected into the agent's instructions alongside the journey prompt.
  • Schedule. A recurring set of test runs. You pick which journeys to include, set a frequency (daily, hourly, etc.), and Aiqaramba runs them automatically. Schedules are budget-aware — if you have more journeys than your daily budget allows, the system prioritizes the most important and least recently run journeys first, ensuring everything gets covered over time.
  • Finding. A bug, issue, or observation that an agent discovered during a run. Findings have a severity (critical, high, medium, low), screenshots showing what went wrong, and steps to reproduce. When integrations are connected, findings can automatically create issues in GitHub or Linear.
  • Test Plan. A multi-step scenario where journeys are chained together with dependencies. Step B only runs after step A passes. This lets you orchestrate complex flows like "create an account, then log in with that account, then complete a purchase" where each step depends on the previous one. See the Test Plans guide for details.

How They Fit Together

A project is the top-level container. Inside a project you create journeys (what to test), attach mailboxes when a flow needs to read email, assign roles (how the agent should approach the test), and set up schedules (when to run tests automatically).

When a journey runs, it creates an agent — the ephemeral worker that opens a browser and executes the test. The agent produces findings (bugs and observations) along with screenshots and a full step-by-step trace.

Discoveries are a shortcut to get started. Instead of writing journeys from scratch, you run a discovery to let agents explore your app and suggest journeys for you. You review the suggestions, save the ones you want, and add them to a schedule.

Test plans let you chain journeys into multi-step sequences when the order matters — for example, creating a user in step one and logging in with that user in step two.

A typical workflow looks like this:

  • 1. Create a project for the application you want to test.
  • 2. Run a discovery to map the app and get journey suggestions.
  • 3. Create journeys from the suggestions or write your own.
  • 4. Set up a schedule to run your journeys automatically on a recurring basis.
  • 5. Review findings from each run and iterate on your journeys as needed.

Coverage Tiers

Journeys are organized into five tiers, from the most basic checks to the most thorough. Each tier builds on the previous one. When naming your journeys, prefix them with the tier so you can quickly see what level of coverage you have.

  • Authentication. Can users reach the app and log in? The most fundamental check. Example: "Login" — navigate to the login page, enter the test account email and password, and verify the dashboard loads.
  • Navigation. Can users reach all the major sections of the app? Tests that the main navigation, sidebar links, and key pages are all accessible. Example: "Main Navigation" — click through each top-level menu item and verify the corresponding page loads.
  • Core features. Do the main features actually work? Tests individual features like creating a record, submitting a form, or uploading a file. Example: "Create Invoice" — create a new invoice with realistic data and verify it appears in the invoice list.
  • End-to-end flows. Do multi-step business processes complete end-to-end? Tests sequences that span multiple features. Example: "Invoice to Payment" — create an invoice, send it for approval, approve it, and verify the payment is processed.
  • Edge cases. Does the app handle bad input, edge cases, and error states gracefully? Tests what happens when things go wrong. Example: "Empty Form Submission" — submit every required form without filling in any fields and verify that helpful error messages appear.

A well-covered application has journeys across all these categories. Start with authentication (can you log in?) and core features (do the main things work?), then expand into navigation, end-to-end flows, and edge cases as you scale your test suite.