# Donobu – Continuous Quality for Your Web App

## Overview
Donobu is an agentic platform that enables QA, engineering, product, design, marketing, and legal teams to rapidly **test and validate** websites and web applications. Using a **bring-your-own-LLM** approach (or entirely manual control), Donobu helps you create browser **automations and tests** from natural language prompts. When you specify a website URL and an objective, Donobu’s **FlowPilot** agent (or manual mode) will **navigate, verify, and record** the steps, ultimately generating a Playwright script in TypeScript for deterministic replay (**rerun**) or integration into your test automation pipeline.

> **Positioning Note**: Donobu is designed as an **AI/manual tester** companion, perfect for complementing AI code-writer tools. While it can handle generic automation tasks (e.g., setting up a test environment, routine employee workflows), **its primary focus is on robust testing and continuous quality** across your web app lifecycle.

### Key Highlights
- **Agentic and Manual Testing**  
  Automate website interactions with AI-driven or manual step recording, ideal for achieving wide test coverage.
- **No Coding Required**  
  Simply provide an objective; Donobu’s FlowPilot figures out the necessary steps, letting anyone create tests.
- **Scalable**  
  Export test flows as TypeScript, integrate them into CI/CD pipelines, and reference previous browser states to streamline QA processes.
- **Smart vs. Standard Actions**  
  AI-powered “smart” actions (e.g., semantic assertions, text analysis) blend seamlessly with “standard” user-like actions (click, navigate, hover).

---

## Flows in Donobu
A **flow** is a sequence of actions intended to accomplish a specific **testing or validation objective**. Flows can be built in two ways:

1. **Autonomous Mode (FlowPilot)**  
  - Donobu’s FlowPilot agent autonomously determines how to fulfill the given test objective.  
  - Users can pause the agent’s navigation at any time if manual oversight is needed.

2. **Manual Mode**  
  - The user navigates the website themselves while Donobu records each step.  
  - Perfect for highly specific test paths or scenarios requiring direct user control.

### Iterations and Stopping Criteria
Donobu applies **iteration limits** to avoid infinite loops or excessive exploration when in **Autonomous** mode. Once this threshold is reached, FlowPilot automatically stops and reports progress or results.

### Saved Browser State
For login flows or complex test pre-conditions, Donobu can **save browser state** (session, cookies, etc.). Subsequent flows can reference that saved state by using the previous flow’s ID or name—especially useful for multi-part test sequences.

## Terminology

- **Actions**  
  Individual steps in a flow (e.g., navigating, clicking, asserting).
- **Flow**  
  A collection of actions that fulfill a particular objective or test scenario.
- **FlowPilot**  
  The autonomous navigator (formerly “Flow Runner”) that interprets your test prompts and site context to decide the optimal sequence of steps.
- **Rerun**  
  A deterministic re-execution of a previously discovered flow, free from additional LLM inferences.

## Supported LLMs and Keys
Donobu supports user-provided API keys for:
1. **OpenAI** (e.g., GPT-4, GPT-4o-mini)
2. **Google Gemini**
3. **Anthropic Claude**

As new multimodal or specialized models emerge, Donobu’s “bring-your-own-LLM” approach makes it easy to adopt them. Your keys are stored locally for security and **never** transmitted externally by Donobu.

## Run Modes
Donobu flows can run in one of three modes, depending on how you want the test or automation to execute:

- **AUTONOMOUS**  
  FlowPilot (the AI agent) decides how to achieve the objective, stopping once successful or hitting the iteration limit.

- **INSTRUCT**  
  Human-driven mode (referred to as “manual” in the UI). The flow ends only when the user explicitly stops or completes it.

- **DETERMINISTIC**  
  A step-by-step “on rails” mode that typically **reruns** a previously saved flow, executing predefined actions without additional AI inference.

## Key Features

1. **FlowPilot (Agentic Navigation)**  
   - Tests or verifies your site by autonomously finding the best sequence of actions.  
   - Easily paused via an on-page overlay for manual intervention.

2. **Rerun**  
   - Replays existing flows deterministically—ideal for regression testing and CI environments.

3. **Export Code**  
   - Produces Playwright TypeScript scripts ready for deeper CI/CD integration and advanced custom checks.

4. **API Support**  
   - Donobu runs a local server (`http://localhost:31000/api`) to programmatically create and manage flows—great for DevOps or automated QA pipelines.

5. **Semantic Assertions & Smart Actions**  
   - Leverage AI to perform advanced checks (e.g., brand style, text classification, AI chatbot verification) that go beyond standard DOM-based testing.

6. **Manual Control & Recording**  
   - Record user-driven testing steps in a flow, bypassing the AI layer entirely.

## Enhanced Prompting Guidelines
- **End-to-End Test Case Structure**:  
  Prompts should be written like an end-to-end test case with a clearly defined end state. Describe the expected final condition or outcome of the test.

- **Magic Keyword “Assert”**:  
  Use the word **"Assert"** in your prompts to indicate a test assertion. This keyword signals that the assertion should check a condition that returns true or false, ensuring that key checkpoints are validated.

- **Bounded Requests to Prevent Infinite Loops**:  
  When instructing the system to process lists or iterative steps (e.g., “test the first 3 links of the results”), explicitly bound the request to a specific number or condition. This prevents unintentional infinite loops or excessive processing.

- **Clear and Descriptive Objectives**:  
  Objectives or prompts should describe the desired outcome clearly without necessarily using numeric steps. For example, instead of "1. Login, 2. Navigate, 3. Validate", use a descriptive statement such as "Complete the login process, navigate to the dashboard, and verify that the user’s name appears correctly."

- **Optional Keywords for Flow Control (suggestion)**:  
  Consider introducing keywords like **"Wait"** for delays or **"Retry"** for reattempting steps, providing further control over the flow execution.  
  *(This is an optional guideline to expand the control vocabulary.)*

- - **Error Handling Guidelines:**  
  Specify clear instructions on how to handle unexpected results or errors during the flow. For example, incorporate a "Make comment and stop" to manage exceptions.

## Comprehensive API Reference

When the Donobu desktop app is running locally, it spins up a full-featured API server (defaulting to port `31000`). The API provides comprehensive endpoints for programmatic flow management, configuration, agent control, and system monitoring.

### Core API Endpoints

#### Flow Management
- **POST /api/flows** - Create new browser automation flows
- **GET /api/flows** - List and query existing flows with filtering
- **GET /api/flows/{id}** - Retrieve specific flow details and metadata
- **PUT /api/flows/{id}** - Update existing flow configuration
- **DELETE /api/flows/{id}** - Remove flows from the system
- **POST /api/flows/{id}/run** - Execute flows in various run modes
- **GET /api/flows/{id}/runs** - Access execution history and logs
- **GET /api/flows/{id}/rerun** - Get deterministic replay configuration
- **GET /api/flows/{id}/code** - Export flows as Playwright TypeScript

#### GPT Configuration Management
- **GET /api/configs** - List available GPT configurations
- **POST /api/configs** - Create new GPT model configurations
- **GET /api/configs/{id}** - Retrieve configuration details
- **PUT /api/configs/{id}** - Update GPT settings and prompts
- **DELETE /api/configs/{id}** - Remove configurations

#### Agent System
- **GET /api/agents** - List available AI agents and capabilities
- **POST /api/agents** - Register custom agents with specific behaviors
- **GET /api/agents/{id}** - Get agent details and configuration
- **PUT /api/agents/{id}** - Update agent settings and parameters
- **DELETE /api/agents/{id}** - Remove custom agents

#### Tool Integration
- **GET /api/tools** - List available automation tools and actions
- **POST /api/tools** - Register new custom tools with JavaScript implementation
- **GET /api/tools/{id}** - Retrieve tool details and schema
- **PUT /api/tools/{id}** - Update tool implementation
- **DELETE /api/tools/{id}** - Remove custom tools

#### System Operations
- **GET /api/system/health** - System health status and diagnostics
- **GET /api/system/version** - API version and build information
- **GET /api/system/capabilities** - Supported browser features and limits

---

### 📅 Create a Flow via API
```http
POST /api/flows
Content-Type: application/json
```
#### Request Body:
```json
{
  "targetWebsite": "https://www.example.com",
  "overallObjective": "Find the best deal on a new laptop.",
  "name": "My Awesome Flow",
  "browser": {
    "initialState": {
      "type": "id",
      "value": "a1b2c3d4-e5f6-7890-1234-567890abcdef"
    },
    "persistState": true,
    "using": {
      "type": "device",
      "deviceName": "Desktop Chromium",
      "headless": true
    }
  },
  "callbackUrl": "https://www.example.com/callback",
  "customTools": [
    {
      "name": "MyCustomTool",
      "description": "This tool does something special.",
      "inputSchema": {
        "type": "object",
        "properties": {
          "input": {
            "type": "string",
            "description": "The input for the tool."
          }
        }
      },
      "javascript": "console.log('Hello, world!');"
    }
  ],
  "maxIterations": 10,
  "gptConfigNameOverride": "My GPT Config",
  "defaultToolTipDurationMilliseconds": 2247,
  "initialRunMode": "AUTONOMOUS",
  "isControlPanelEnabled": true,
  "allowedTools": [],
  "toolCallsOnStart": [],
  "resultinputSchema": {
    "type": "object",
    "properties": {
      "result": {
        "type": "string"
      }
    }
  }
}
```
**Minimum required fields**:  
- `targetWebsite` *(string)*  
- `overallObjective` *(string)* (or an alternative if your flow is purely manual/deterministic)

**Common optional fields**:  
- `deviceName` to choose the browser options - `Desktop Chrome`, `Desktop Safari`, `Desktop Firefox`, `iPhone 14`, `Pixel 7`, `iPad Pro 11`  
- `maxIterations` to bound AI exploration in AUTONOMOUS mode

---

### 🔍 Query Flows
```http
GET /api/flows?name=My%20Flow&runMode=AUTONOMOUS&state=SUCCESS&startedAfter=1700000000000&limit=5
```
#### Response (200 OK):
```json
{
  "flows": [
    {
      "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
      "name": "My Flow",
      "state": "SUCCESS",
      "startedAt": 1700056789123
    }
  ],
  "nextPageToken": null
}
```

---

### 🗒️ Get Flow Metadata
```http
GET /api/flows/{flowId}
```
Returns the metadata for a specific flow.

---

### ❌ Delete a Flow
```http
DELETE /api/flows/{flowId}
```
Removes a flow from the system.

---

### ⏪ Rerun a Flow
```http
GET /api/flows/{flowId}/rerun
```
Returns a deterministic version of the flow configuration, suitable for replay.

---

### 💻 Export Flow as Code
```http
GET /api/flows/{flowId}/code
```
Returns a code (TypeScript Playwright) representation of the flow.

---

### Advanced API Features (2025 Schema)

#### Enhanced Query and Filtering
- **Advanced Filtering**: Filter flows by `name`, `runMode`, `state`, `startedBefore`, `startedAfter`, `targetWebsite`, and custom metadata
- **Pagination**: Efficient listing with `limit` and `pageToken` parameters for large datasets
- **Sorting**: Sort results by creation time, execution time, success rate, or custom criteria

#### Flexible Browser Configuration
- **Device Emulation**: Use predefined devices (`Desktop Chrome`, `iPhone 14`, `Pixel 7`, `iPad Pro 11`) or custom viewport settings
- **Remote Instances**: Connect to remote browser instances or cloud-based testing environments
- **BrowserBase Integration**: Seamless integration with BrowserBase for scalable browser automation

#### Custom Tool Ecosystem
- **JavaScript Tools**: Define custom tools with JavaScript implementation and JSON schema validation
- **Tool Composition**: Chain multiple tools together for complex automation workflows
- **Tool Calls on Start**: Execute initialization tools automatically when flows begin
- **Dynamic Tool Loading**: Load tools dynamically based on flow requirements

#### Result Management and Callbacks
- **Structured Results**: Define custom result schemas using `resultInputSchema` for consistent data extraction
- **Webhook Integration**: Configure callback URLs to receive real-time notifications about flow completion and status changes
- **Data Persistence**: Automatically save flow results, screenshots, and extracted data with configurable retention policies

#### Advanced Flow Control
- **Conditional Execution**: Support for conditional logic and branching within flows
- **Error Handling**: Robust error handling with retry mechanisms and fallback strategies
- **State Management**: Advanced browser state management including cookies, local storage, and session data
- **Parallel Execution**: Run multiple flows concurrently with resource management and throttling

You can integrate Donobu flows into your testing pipelines, CI/CD workflows, or QA environments with minimal configuration. The comprehensive API supports both autonomous AI-driven exploration and deterministic script replay, making it suitable for development, staging, and production testing scenarios.

## Available Actions

Below is a selection of **testing-oriented** actions supported by Donobu. Some are purely mechanical (standard); others incorporate AI logic (smart):

- **Go to Webpage** *(standard)*  
  Load a new URL in the browser.
- **Click** *(standard)*  
  Click a specified element (e.g., button, link).
- **Input Text** *(standard)*  
  Type text into a field, such as usernames or form data.
- **Detect Broken Links** *(standard)*  
  Check for 404 or otherwise dead links across a page.
- **Analyze Page Text** *(smart)*  
  Read and interpret textual content using an LLM.
- **Assert** *(smart)*  
  Visually verify or check a condition on a webpage using the **Assert** keyword. This action validates whether a specific state (such as brand consistency, text accuracy, or element presence) is true or false.
- **Run Accessibility Test** *(standard)*  
  Evaluate WCAG compliance for universal design.
- **Cookie Report** *(smart)*  
  Inspect cookies for compliance and list their potential uses, with prompt-based analysis if needed.
- **Mark Objective Complete** *(standard)*  
  Ends the flow after successful test completion.
- **Pause for User Interaction** *(standard)*  
  Temporarily halt FlowPilot so a user can handle manual steps like entering sensitive information.

## Varied Testing Scenarios & Example Flows

Below are sample test scenarios from different teams highlighting Donobu’s capacity for **verification**, **reporting**, and **continuous QA**.

### Example 1 – Multi-Step Purchase Flow (E-Commerce)
- **URL**: [https://www.bestbuy.com](https://www.bestbuy.com)  
- **Objective**:  
  1. Search for “gaming laptop”  
  2. Filter by “Price: High to Low” and “4-star or higher” rating  
  3. Add the first item to cart and proceed to checkout  
  4. Stop before payment entry  
- **Key Notes**:  
  - **AUTONOMOUS** with `maxIterations = 15` prevents infinite loops.  
  - Incorporates a **Pause** action if user input is required.

### Example 2 – Content Audit and Summarization (Editorial Team)
- **URL**: [https://www.bloomberg.com](https://www.bloomberg.com)  
- **Objective**:  
  Extract the titles of the first five news articles on the homepage, categorize each article by topic (e.g., finance, tech, politics), and summarize key points in bullet form.  
- **Key Notes**:  
  - Relies on **Analyze Page Text** and semantic checks to ensure the categorization and summaries are accurate.
  - Limits processing to a specified number of articles to prevent looping.

### Example 3 – Login State Preservation (Product/QA)
- **URL**: [https://stage.yourapp.com](https://stage.yourapp.com)  
- **Objective**:  
  1. Log in with test credentials  
  2. Update user display name in “Account Settings”  
  3. Mark the flow complete and **persist browser state**  
- **Key Notes**:  
  - Future flows can load this saved session to test deeper features.  
  - Ideal for advanced QA use cases.

### Example 4 – AI Chatbot Verification (Engineering/QA)
- **URL**: [https://www.customer-support.com](https://www.customer-support.com)  
- **Objective**:  
  Open the embedded chatbot, inquire about subscription plan details, verify that at least three valid plan tiers are presented, and ensure the reply references plan cost and usage caps.  
- **Key Notes**:  
  - Shows Donobu’s open-ended test approach with iteration limits to keep FlowPilot on track.

### Example 5 – Accessibility and Brand Consistency (Legal/Design)
- **URL**: [https://www.federalreserve.gov](https://www.federalreserve.gov)  
- **Objective**:  
  Execute an accessibility test to identify WCAG issues, verify that brand colors adhere to official style guidelines, and generate a final JSON report for legal review.  
- **Key Notes**:  
  - Combines standard “Run Accessibility Test” plus a “semantic brand check.”

---

## Frequently Asked Questions

1. **How can I start using Donobu?**  
   Download Donobu and contact us if you’re interested in advanced features—we’ll be happy to guide you.

2. **Is Donobu free to use?**  
   Yes! Donobu is currently free. You can use it with your own LLM model or record flows manually at no cost.

3. **Can I share Donobu with my friends or team?**  
   Absolutely—Donobu is built for collaboration.

4. **What devices can I use Donobu on?**  
   Donobu currently works on **macOS**. We plan to expand to more platforms soon.

5. **Do I need coding skills to use Donobu?**  
   No coding required. Donobu’s intuitive interface and natural language prompts let anyone build test flows.

---

## Conclusion
Donobu elevates web testing and continuous quality assurance, helping teams verify websites, extract data, and confirm brand consistency. Whether you use FlowPilot’s AI-driven navigation or record steps manually, Donobu’s **blend of smart and standard actions** enables thorough testing. With iteration limits, saved browser states, and robust API endpoints, it seamlessly integrates into any QA or DevOps pipeline.

Start exploring Donobu’s capabilities today, and reach out if you need any clarification or advanced support!