From 30e31279312e23070d78968c8e344735f7bca67f Mon Sep 17 00:00:00 2001
From: Marcel Veselka <marcel.veselka@tesena.com>
Date: Mon, 1 Sep 2025 20:23:10 +0200
Subject: [PATCH 1/2] feat: more details about tools and assertions, nav
 improvements

---
 docs/{bot.md => ai-agent.md}                  |   4 +-
 .../pom-login-example.md                      |   0
 docs/concepts/prompting-guidelines.md         |   6 +
 docs/concepts/tools-and-assertions.md         | 137 ++++++++++++++++++
 docs/index.md                                 |   1 +
 mkdocs.yml                                    |   6 +-
 6 files changed, 150 insertions(+), 4 deletions(-)
 rename docs/{bot.md => ai-agent.md} (89%)
 rename docs/{automation => concepts}/pom-login-example.md (100%)
 create mode 100644 docs/concepts/tools-and-assertions.md

diff --git a/docs/bot.md b/docs/ai-agent.md
similarity index 89%
rename from docs/bot.md
rename to docs/ai-agent.md
index dd989c4..65ab1df 100644
--- a/docs/bot.md
+++ b/docs/ai-agent.md
@@ -22,7 +22,8 @@ After creating a project, you have two options to add tests:
 
 **A. Generate new tests automatically**
 
-- Start a [NEW ANALYSIS](analysis.md) to let the system create tests for you.
+- Start a [NEW ANALYSIS](concepts/analysis-process.md) to let the system create tests for you.
+- Learn about [🛠️ Tools & Assertions](tools-and-assertions.md) to understand how the agent interacts with your app.
 
 **B. Integrate your existing tests**
 
@@ -33,7 +34,6 @@ After creating a project, you have two options to add tests:
   - [Robot Framework](robot-framework/01-getting-started.md)
   - [WebdriverIO](webdriverio-visual-testing.md)
 
-
 ## 4. Run tests
 
 Once your tests are ready:
diff --git a/docs/automation/pom-login-example.md b/docs/concepts/pom-login-example.md
similarity index 100%
rename from docs/automation/pom-login-example.md
rename to docs/concepts/pom-login-example.md
diff --git a/docs/concepts/prompting-guidelines.md b/docs/concepts/prompting-guidelines.md
index 3bdb63d..66106af 100644
--- a/docs/concepts/prompting-guidelines.md
+++ b/docs/concepts/prompting-guidelines.md
@@ -291,3 +291,9 @@ When applying POM patterns, also verify:
 - [ ] **Error handling** requirements are outlined
 - [ ] **Example usage** demonstrates page object interaction
 - [ ] **Single responsibility** principle is maintained
+
+## Related topics
+
+- [🛠️ Tools & Assertions](tools-and-assertions.md) - Understand how the agent interacts with your app and validates outcomes
+- [✨ Analysis Process](analysis-process.md) - Learn about the complete analysis workflow
+- [🔗 Analysis Inputs](analysis-inputs.md) - Discover what inputs improve test analysis quality
diff --git a/docs/concepts/tools-and-assertions.md b/docs/concepts/tools-and-assertions.md
new file mode 100644
index 0000000..4560c2b
--- /dev/null
+++ b/docs/concepts/tools-and-assertions.md
@@ -0,0 +1,137 @@
+---
+title: Tools & Assertions
+---
+
+# Tools & Assertions (Wopee.io)
+
+## What this page covers
+
+How the agent interacts with your app, how it validates outcomes, and how locators are chosen. After a scenario runs, Wopee.io generates **plain test code** (e.g., Playwright) that you can run anywhere—**no LLMs or Wopee.io runtime required**.
+
+---
+
+## Execution flow (at a glance)
+
+1. **Select interaction tool** (click, type, select, etc.) for the desired action.
+2. **Agent automatically chooses locator strategy** (ARIA/HTML/visual) based on the tool and target element.
+3. **Perform interactions** using the selected tool and optimal locator.
+4. **Validate results** with assertions (text, visibility, visual).
+5. **Export deterministic code** that mirrors the exact tools and locators used.
+
+---
+
+## Interaction tools
+
+Use these to drive the UI.
+_(Tip: prefer semantic/accessible targets first; fall back to visual only when needed.)_
+
+- **Click** – Click an element once.
+- **Double click** – Double-click an element.
+- **Visual click** – Click by visual position (e.g., icon/button without stable DOM locator).
+- **Fill** – Type text into an input/textarea.
+- **Select** – Choose an option in a `<select>` or custom dropdown.
+- **Hover** – Move the pointer over an element (tooltips/menus).
+- **Press** – Send keyboard keys or combos (e.g., `Enter`, `Ctrl+S`).
+- **Navigate to URL** – Open a specific URL or path.
+- **Add cookie** – Set a cookie (auth/session/bootstrap).
+- **Upload file** – Attach a local file to a file input.
+
+**Tool-locator relationship**
+
+The tool you select influences how the agent chooses locators:
+
+- **Standard tools** (Click, Fill, Select) → Agent prefers ARIA/HTML locators
+- **Visual tools** (Visual click, Visual assert) → Agent automatically uses visual location strategies
+- **Navigation tools** (Navigate to URL) → No locator needed
+- **System tools** (Add cookie, Upload file) → Agent finds the appropriate input elements using DOM locators
+
+## Assertion tools
+
+Use these to prove the UI is in the expected state.
+
+- **Verify visibility** – Assert that an element is rendered and visible.
+- **Contain text** – Assert an element's text contains a string or regex.
+- **Visual assert** – LLM-assisted visual check written in natural language, e.g.,
+  "**Shopping cart shows a badge with 4 items**."
+  _Great for UI semantics that are hard to express via raw locators; avoid for pixel-perfect needs—use DOM/text assertions instead when possible._
+
+---
+
+## Custom tool
+
+Provide a short instruction (natural language). The agent will **choose the right tool automatically**, **select the optimal locator strategy** for each element, and Wopee.io will **translate it into explicit steps** in the generated code.
+_Example:_ "Open settings and enable dark mode" → navigate, click toggles, and assert theme change.
+
+!!! note "When to use custom tools"
+
+    **Use specific tools when possible**: The more specific you are with tool selection, the more stable and predictable the execution will be. Custom tools are helpful for agent experimentation and fine-tuning behavior, but should only be used when there isn't a specific tool available for your needs.
+
+---
+
+## Locator strategies (automatic selection)
+
+The agent automatically selects the optimal locator strategy based on the tool you choose and the target element:
+
+1. **ARIA tree (preferred)** – Role/name-based locators from accessible markup (stable and intent-focused).
+2. **HTML attributes** – IDs, data-test IDs, classes, and CSS/XPath (use data-test IDs for stability).
+3. **Visual location** – x, y or image heuristics (last resort for canvas, icons without DOM hooks, etc.).
+
+**How it works**
+
+- **Tool-driven selection**: When you choose a tool (e.g., "Click"), the agent analyzes the target element and automatically picks the best locator strategy.
+- **Fallback logic**: If the preferred strategy fails, the agent automatically tries the next best option.
+- **Code generation**: The selected locator strategy is directly used in the generated test code.
+
+**Guidance**
+
+- The agent aims for **stable, readable locators** (data-test IDs > ARIA > HTML > visual).
+- **Visual tools** (like "Visual click") automatically trigger visual location strategies.
+- Keep assertions **specific and minimal**: verify what proves the behavior, not everything on the page.
+
+---
+
+## Code generation
+
+After a successful agent run, Wopee.io emits **deterministic test code** that exactly mirrors the tools you selected and the locator strategies the agent automatically chose. The generated code uses the same interaction tools and locators that were used during the agent's execution, ensuring consistency between what the agent did and what your tests will do. You can commit this code to your repo and run it in CI/CD without Wopee.io or LLMs.
+
+---
+
+## Example (concise)
+
+1. Navigate to `/cart`
+2. Click **Checkout**
+3. Fill **Email** = `alice@example.com`
+4. Press **Enter**
+5. **Verify visibility** of **Order summary**
+6. **Contain text** on **Total** matches `/€\d+\.\d{2}/`
+
+---
+
+## Good practices
+
+!!! tip "Tools & Assertions best practices"
+
+    - **Trust the agent's locator selection**: The agent automatically chooses the best locator strategy based on your tool selection
+    - **Use data-test IDs**: Add stable identifiers to your elements for reliable testing (the agent will prefer these)
+    - **Keep assertions focused**: Verify only what proves the behavior, not everything on the page
+    - **Reserve visual tools**: Use visual clicks/asserts only when DOM selection isn't possible
+    - **Write clear custom instructions**: Be specific about what you want the agent to accomplish
+    - **Let the agent handle complexity**: Focus on what you want to test, not how to locate elements
+    - **Configure interaction rules**: Use project context, code examples, and code rules to specify preferred interaction and assertion patterns
+
+!!! note "Advanced configuration options"
+
+    You can customize interaction and assertion behavior using:
+
+    - **Project context** (all plans): Define application-specific rules and preferences
+    - **Code examples** (Enterprise & Premium): Provide sample code patterns for the agent to follow
+    - **Code rules** (Enterprise & Premium): Set specific coding standards and conventions
+
+    These features help ensure consistent tool usage and code generation across your test suite.
+
+## Related topics
+
+- [Getting Started with bot testing](/bot)
+- [Analysis Process](/concepts/analysis-process)
+- [Prompting Guidelines](/concepts/prompting-guidelines)
+- [Project Context](/project-context)
diff --git a/docs/index.md b/docs/index.md
index e5c87d2..728a02b 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -42,6 +42,7 @@ Unlike traditional test automation tools, Wopee.io does not require any preparat
 ## Start with bot testing : Step by step
 
 - See detailed [📙 Getting Started with bot testing](bot.md) section
+- Learn about [🛠️ Tools & Assertions](tools-and-assertions.md) and how the agent works
 - Understand [📖 Vocabulary](glossary.md) of 🐒
 
 ## Wopee.io Integrations
diff --git a/mkdocs.yml b/mkdocs.yml
index 70b8b7e..3d7ba4a 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -1,11 +1,13 @@
 site_name: Wopee.io
 nav:
-  - 🚀 Autonomous Testing: index.md
+  - 🚀 Welcome!: index.md
+  - 🤖 Getting started: ai-agent.md
   - Concepts:
       - ✨ Analysis - Process: concepts/analysis-process.md
       - 🔗 Analysis - Inputs: concepts/analysis-inputs.md
       - 📖 Prompting Guidelines: concepts/prompting-guidelines.md
-      - 📃 POM example - Login: automation/pom-login-example.md
+      - 🛠️ Tools & Assertions: concepts/tools-and-assertions.md
+      - 📃 POM example - Login: concepts/pom-login-example.md
   - Visual Testing with...:
       - ≫ Cypress:
           - Getting started: cypress/01-getting-started.md

From cce1f1c76a376f118bad83feb717c321ebdcc06b Mon Sep 17 00:00:00 2001
From: Marcel Veselka <marcel.veselka@tesena.com>
Date: Mon, 1 Sep 2025 20:30:29 +0200
Subject: [PATCH 2/2] feat: update title and description to reflect AI Testing
 Agents for web apps

---
 docs/index.md | 7 +++++--
 1 file changed, 5 insertions(+), 2 deletions(-)

diff --git a/docs/index.md b/docs/index.md
index 728a02b..8428079 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -1,12 +1,15 @@
 ---
-title: Autonomous testing plarform
+title: AI Testing Agents for your web apps
 ---
 
-# Welcome to Wopee.io
+# AI Testing Agents for your web apps
 
 Wopee.io is a regression software testing tool for web apps that rapidly speeds up and simplifies testing preparation and test execution.
 Unlike traditional test automation tools, Wopee.io does not require any preparation or programming (tests are generated) and maintenance is easier.
 
+Our AI Testing Agents explore your app like a human tester, learn its flows, and autonomously generate, run, and maintain end-to-end tests.
+The output is deterministic test code you can run anywhere. No LLMs or Wopee.io runtime required.
+
 ## Features
 
 <div class="grid cards" markdown>