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

Merged
merged 2 commits into from
Nov 15, 2025
Merged

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

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
af871ee
feat: Enhance README with product pitch and ELI5 technical explanation
Devasy23 Nov 8, 2025
9344712
Refactor README by removing redundant sections
monkscode Nov 15, 2025
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)






    

    

    

  
    ```






      


  
        

      
  
    
    

      
      
            

      

      Comment on lines

    
      11
     to 
      17
    

  


  





  

    

        

        

  

    

      

          
    
    

  


        
            
  
      
              Copy link

  

        
      

    


    

        

  
    Contributor


        

    

  


  

    

      
          @coderabbitai
      

      
            coderabbitai
  bot

      

      

      


        Nov 15, 2025


      
    


  




        

      

  

  
 

  
    

    
Choose a reason for hiding this comment


    

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


    

      
      



  



  
    

      
⚠️ Potential issue | 🟠 Major



🧩 Analysis chain

Fix markdown linting violation: add language specifier to code block (MD040).


The ASCII diagram code block is missing a language identifier. Per the past review feedback and markdown standards, this and other fenced code blocks should specify their language.


Apply this diff to fix the code block:


-```
+```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)
-```
+```




🏁 Script executed:


#!/bin/bash
# Verify code block at lines 11-17 and scan for all MD040 violations

echo "=== Lines 11-17 of README.md ==="
sed -n '11,17p' README.md

echo -e "\n=== Scanning for all fenced code blocks without language specifiers (MD040) ==="
# Find all opening ``` fences and check if they have a language specifier on the same line
rg -n '^\s*```\s*$' README.md | head -20

echo -e "\n=== Quick Start section (lines 72-108) ==="
sed -n '72,108p' README.md | head -30


Length of output: 313




🏁 Script executed:


#!/bin/bash
# Verify code block at lines 11-17 and scan for all MD040 violations

echo "=== Lines 11-17 of README.md ==="
sed -n '11,17p' README.md

echo -e "\n=== Scanning for all fenced code blocks without language specifiers (MD040) ==="
# Find all opening ``` fences that are NOT followed by a language identifier
rg -n '^\s*```\s*$' README.md

echo -e "\n=== Quick Start section (around lines 72-108) ==="
sed -n '70,110p' README.md

echo -e "\n=== Checking for Windows PowerShell references ==="
rg -in 'powershell|pwsh|windows.*shell' README.md


Length of output: 1629






Fix markdown linting violation: add language specifier to code block (MD040).


The ASCII diagram code block at lines 11–17 is missing a language identifier. This violates markdown linting rule MD040. Additionally, similar violations exist at multiple other code blocks throughout the file (lines 98, 104, 106, 113, 115, 118, 120, 127, 129, 148, 160, 175, 177, 200, 225, 238, 253).


Apply this diff to fix the code block at lines 11–17:


-```
+```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)
-```
+```


For consistency, all fenced code blocks should specify appropriate language identifiers (e.g., bash, python, text, plaintext).



🧰 Tools


🪛 markdownlint-cli2 (0.18.1)

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


(MD040, fenced-code-language)







🤖 Prompt for AI Agents

In README.md around lines 11 to 17, the fenced ASCII-diagram code block lacks a
language specifier causing markdown lint MD040; update the opening fence to
include a language token (e.g., ```text or ```plaintext) so the block becomes a
fenced code block with a language identifier, and apply the same pattern to
other code blocks listed (lines
98,104,106,113,115,118,120,127,129,148,160,175,177,200,225,238,253) for
consistency.





    

  
  




    


        

      
  
  

    
  
    
    

  

  

  



          

      
    








    


  









  


    


  		



    

    

    

  
    







    

    

    

  
    ## 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