Skip to content

feat: Enhance README with product pitch and ELI5 technical explanation #8

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

feat: Enhance README with product pitch and ELI5 technical explanation #8

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
123 changes: 117 additions & 6 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,17 +6,45 @@
![Docker](https://img.shields.io/badge/Docker-Required-blue.svg)
![AI Powered](https://img.shields.io/badge/AI-Powered-purple.svg)

**Transform plain English into production-ready test automation.** Mark 1 is an intelligent test generation platform that converts natural language descriptions into executable Robot Framework code using a sophisticated multi-agent AI system. No coding required—just describe what you want to test.
**Transform plain English into production-ready test automation.** Mark 1 is your one-stop solution for writing automation tests without coding. Just describe what you want to test in plain English, and watch it generate working Robot Framework tests automatically. Write once, execute infinitely—even if your application changes!

```
Copy link
Contributor

@coderabbitai coderabbitai bot Nov 8, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🛠️ Refactor suggestion | 🟠 Major

Add language identifiers to fenced code blocks per markdown formatting standards.

Seven code blocks are missing language specifiers (MD040 violations). For ASCII diagrams, use ```text or ```plaintext; for shell commands, use ```bash; for test examples, use ```robot.

Apply these diffs to fix the markdown linting violations:



+text "Open Flipkart and search for shoes and then get the first product name" ↓ [4 AI Agents Working Together] ↓ ✅ Working Robot Framework Test (Can run forever) -

+```



```diff
-```
+```plaintext
 "Search for 'blue shoes' on the website, verify results appear, 
 and check that the first product has a price"
-```
+```



-```
+```plaintext
 "Login with credentials admin@company.com, navigate to settings, 
 change password to NewPassword123, and verify success message"
-```
+```


-```
+```plaintext
 "Fill patient form with John Doe, age 30, select blood type O+, 
 upload medical record, and submit"
-```
+```


-```
+```plaintext
 "Create new project, add 3 team members, set privacy to private, 
 and verify they can access the project"
-```
+```


-```
+```plaintext
 "Open website on mobile viewport, search for items, 
 add to cart, and proceed to checkout"
-```
+```




+```text


    

  1. 

    YOU:  "Go to Google and search for 'cats'"
    

    2. 

  2. 

    ROBOT THINKS: "OK, let me break that down:
    

      

    • Step 1: Go to Google.com
      • 

    • Step 2: Find the search box
      • 

    • Step 3: Type 'cats'
      • 

    • Step 4: Press Enter"
      • 

    

    3. 

  3. 

    ROBOT LOOKS: (uses AI eyes to see the website)
    
"I see a search box with id='search'
    
I see a search button with class='submit'"
    

    4. 

  4. 

    ROBOT WRITES: (generates test code in Robot Framework)
    
"Open Browser → Fill Text in search box → Click button"
    

    5. 

  5. 

    ROBOT TESTS: (runs the test in a clean sandbox)
    
"✅ Test passed! Everything worked!"
    
- +
    

    6. 






Also applies to: 70-70, 78-78, 86-86, 94-94, 102-102, 184-184

<details>
<summary>🧰 Tools</summary>

<details>
<summary>🪛 markdownlint-cli2 (0.18.1)</summary>

11-11: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

</details>

</details>

<details>
<summary>🤖 Prompt for AI Agents</summary>




In README.md around lines 11, 70, 78, 86, 94, 102 and 184, several fenced code

blocks lack language identifiers; update each opening fence to include the appropriate language specifier (usetext for ASCII diagrams, plaintext for plain text/test examples, bash for shell commands, and robot for Robot Framework examples) so each code block begins with the correct backticks plus language token and leave the existing closing  unchanged.



</details>

<!-- This is an auto-generated comment by CodeRabbit -->


    

  
  




    


        

      
  
  

    
  
    
    

  

  

  



          

      
    








    


  









  


    


  		



    

    

    

  
    "Open Flipkart and search for shoes and then get the first product name"






    

    

    

  
                                ↓






    

    

    

  
            [4 AI Agents Working Together]






    

    

    

  
                                ↓






    

    

    

  
        ✅ Working Robot Framework Test






    

    

    

  
        ✅ Working Robot Framework Test (Can run forever)






    

    

    

  
    ```






    

    

    

  
    







    

    

    

  
    ## Why Mark 1?






    

    

    

  
    ## 🚀 What Can Mark 1 Do For You?






    

    

    

  
    







    

    

    

  
    ### ✅ Your One-Stop Solution for Automation Testing






    

    

    

  
    - **No Coding Required** - Write tests in plain English, not Python or JavaScript






    

    

    

  
    - **Works on Any Website** - E-commerce, SaaS, web apps—anything with a UI






    

    

    

  
    - **Generates Professional Code** - Beautiful Robot Framework tests that even manual QAs can read






    

    

    

  
    - **Fast Test Creation** - 20-30 seconds from idea to working test






    

    

    

  
    







    

    

    

  
    ### 📝 Write Once, Execute Infinitely






    

    

    

  
    - **Reusable Tests** - Generate test code once, run it 1000 times






    

    

    

  
    - **Environment Agnostic** - Same test works on dev, staging, and production






    

    

    

  
    - **No Re-recording Needed** - Unlike traditional record-and-playback tools, AI keeps up with UI changes






    

    

    

  
    - **Cost Efficient** - Setup overhead paid once, then unlimited test runs






    

    

    

  
    







    

    

    

  
    ### 🧠 Gets Smarter Over Time






    

    

    

  
    - **Learns Your Architecture** - Remembers common navigation patterns and workflows






    

    

    

  
    - **Contextual Understanding** - AI understands your product's structure and layout






    

    

    

  
    - **Fewer Tokens Over Time** - As it learns your system, it uses fewer AI tokens per test






    

    

    

  
    - **Better Outputs** - More specific, stable, and efficient tests with each run






    

    

    

  
    







    

    

    

  
    ### 👥 Perfect for Manual QA Teams






    

    

    

  
    - **Easy to Read** - Robot Framework syntax is plain English-like, no technical skills needed






    

    

    

  
    - **Self-Documenting** - Test code IS the documentation






    

    

    

  
    - **Low Learning Curve** - Manual QAs can understand and maintain tests immediately






    

    

    

  
    - **Empowerment Without Complexity** - Keep your QA team without forcing them to become developers






    

    

    

  
    







    

    

    

  
    ---






    

    

    

  
    







    

    

    

  
    ## Why Mark 1 Stands Out






    

    

    

  
    







    

    

    

  
    - 🎯 **95%+ Success Rate** - Vision-based element detection that actually works






    

    

    

  
    - ⚡ **3-5x Faster** - Batch processing finds all elements in one session






      

    
        
          
        
        Expand All
    
    @@ -25,7 +53,7 @@
  


    

    

    

  
    - 📦 **Zero Setup** - One command to start, works out of the box






    

    

    

  
    - 🎨 **Beautiful Reports** - Detailed HTML logs for easy debugging






    

    

    

  
    







    

    

    

  
    ## Quick Comparison






    

    

    

  
    ## 📈 Quick Comparison






    

    

    

  
    







    

    

    

  
    | Feature | Mark 1 | Selenium IDE | Playwright Codegen | Manual Coding |






    

    

    

  
    |---------|--------|--------------|-------------------|---------------|






      

    
        
          
        
        Expand All
    
    @@ -35,6 +63,63 @@
  


    

    

    

  
    | **Learning Curve** | None | Low | Medium | High |






    

    

    

  
    | **Maintenance** | Simply Rerun | Re-record | Re-record | Manual updates |






    

    

    

  
    







    

    

    

  
    ## 💼 Real-World Use Cases






    

    

    

  
    







    

    

    

  
    ### 🛍️ E-commerce & Retail






    

    

    

  
    **Scenario**: Test search functionality across your product catalog






    

    

    

  
    ```






    

    

    

  
    "Search for 'blue shoes' on the website, verify results appear, 






    

    

    

  
    and check that the first product has a price"






    

    

    

  
    ```






    

    

    

  
    ✅ **Benefit**: Catch product page layout changes automatically, no re-recording






    

    

    

  
    







    

    

    

  
    ### 🏦 Financial Services






    

    

    

  
    **Scenario**: Test user account workflows






    

    

    

  
    ```






    

    

    

  
    "Login with credentials admin@company.com, navigate to settings, 






    

    

    

  
    change password to NewPassword123, and verify success message"






    

    

    

  
    ```






    

    

    

  
    ✅ **Benefit**: Complex flows are easy to describe, maintained as readable code






    

    

    

  
    







    

    

    

  
    ### 🏥 Healthcare Platforms






    

    

    

  
    **Scenario**: Test patient data entry flows






    

    

    

  
    ```






    

    

    

  
    "Fill patient form with John Doe, age 30, select blood type O+, 






    

    

    

  
    upload medical record, and submit"






    

    

    

  
    ```






    

    

    

  
    ✅ **Benefit**: Non-technical medical staff can verify and understand tests






    

    

    

  
    







    

    

    

  
    ### ☁️ SaaS Applications






    

    

    

  
    **Scenario**: Test multi-page workflows






    

    

    

  
    ```






    

    

    

  
    "Create new project, add 3 team members, set privacy to private, 






    

    

    

  
    and verify they can access the project"






    

    

    

  
    ```






    

    

    

  
    ✅ **Benefit**: Tests stay valid even after UI redesigns with AI adaptation






    

    

    

  
    







    

    

    

  
    ### 📱 Cross-Platform Testing






    

    

    

  
    **Scenario**: Verify workflows on web and mobile-responsive sites






    

    

    

  
    ```






    

    

    

  
    "Open website on mobile viewport, search for items, 






    

    

    

  
    add to cart, and proceed to checkout"






    

    

    

  
    ```






    

    

    

  
    ✅ **Benefit**: Single test description works on responsive designs






    

    

    

  
    







    

    

    

  
    ---






    

    

    

  
    







    

    

    

  
    ## 🎯 Why Choose Mark 1? (The Bottom Line)






    

    

    

  
    







    

    

    

  
    | Your Situation | Mark 1 Solution | Time Saved |






    

    

    

  
    |---|---|---|






    

    

    

  
    | **You have manual QA team** | No coding needed, tests are readable English | ✅ 40-60% faster test creation |






    

    

    

  
    | **UI changes frequently** | Tests auto-adapt via AI | ✅ No test maintenance time |






    

    

    

  
    | **Need tests for new features** | Write tests before code exists | ✅ Test-driven development ready |






    

    

    

  
    | **Legacy testing tools too slow** | Batch element detection | ✅ 3-5x faster than Selenium IDE |






    

    

    

  
    | **Testing is expensive** | Reuse tests indefinitely | ✅ Lower total cost of ownership |






    

    

    

  
    | **Hard to scale QA** | One engineer → 1000 tests | ✅ Enable non-technical QAs |






    

    

    

  
    







    

    

    

  
    ---






    

    

    

  
    







    

    

    

  
    ## 🚀 Quick Start






    

    

    

  
    







    

    

    

  
    ### Prerequisites






      

    
          
            
          
          Expand Down
          
            
          
          Expand Up
    
    @@ -92,7 +177,31 @@ python tools/browser_use_service.py
  


    

    

    

  
    







    

    

    

  
    **Pro Tip:** Be specific about what you want. Mention exact elements like "first product name" or "search button in header".






    

    

    

  
    







    

    

    

  
    ## 🏗️ How It Works






    

    

    

  
    ## 🏗️ How It Works (Explain Like I'm 5)






    

    

    

  
    







    

    

    

  
    **Imagine you're teaching a robot to test your website:**






    

    

    

  
    







    

    

    

  
    ```






    

    

    

  
    1. YOU:  "Go to Google and search for 'cats'"






    

    

    

  
    







    

    

    

  
    2. ROBOT THINKS: "OK, let me break that down:






    

    

    

  
       - Step 1: Go to Google.com






    

    

    

  
       - Step 2: Find the search box






    

    

    

  
       - Step 3: Type 'cats'






    

    

    

  
       - Step 4: Press Enter"






    

    

    

  
    







    

    

    

  
    3. ROBOT LOOKS: (uses AI eyes to see the website)






    

    

    

  
       "I see a search box with id='search'






    

    

    

  
        I see a search button with class='submit'"






    

    

    

  
    







    

    

    

  
    4. ROBOT WRITES: (generates test code in Robot Framework)






    

    

    

  
       "Open Browser → Fill Text in search box → Click button"






    

    

    

  
    







    

    

    

  
    5. ROBOT TESTS: (runs the test in a clean sandbox)






    

    

    

  
       "✅ Test passed! Everything worked!"






    

    

    

  
    ```






    

    

    

  
    







    

    

    

  
    **In Technical Terms:**






    

    

    

  
    







    

    

    

  
    Mark 1 uses a **multi-agent AI system** to transform your natural language into working tests:






    

    

    

  
    







      

    
        
          
        
        Expand All
    
    @@ -102,7 +211,7 @@ Your Query → [AI Processing] → Robot Framework Code → Execution → Result
  


    

    

    

  
    







    

    

    

  
    **The Process:**






    

    

    

  
    1. **Intelligent Planning** - Query analyzed and broken into precise steps






    

    

    

  
    2. **Smart Element Detection** - AI finds web elements with 95%+ accuracy






    

    

    

  
    2. **Smart Element Detection** - AI finds web elements with 95%+ accuracy (using computer vision)






    

    

    

  
    3. **Code Generation** - Transforms steps into production-ready Robot Framework code






    

    

    

  
    4. **Quality Assurance** - Validates code before execution






    

    

    

  
    5. **Isolated Execution** - Runs in clean Docker containers






      

    
        
          
        
        Expand All
    
    @@ -113,6 +222,8 @@ Your Query → [AI Processing] → Robot Framework Code → Execution → Result
  


    

    

    

  
    - ✅ Real-time progress updates






    

    

    

  
    - ✅ Validated locators that work on dynamic websites






    

    

    

  
    







    

    

    

  
    **Want deeper details?** See the [Architecture Documentation](docs/ARCHITECTURE.md) for the full technical breakdown.






    

    

    

  
    







    

    

    

  
    ## 📁 Project Structure






    

    

    

  
    







    

    

    

  
    ```






  

    
          
            
          
          Expand Down