Markdown-based Automation Framework v2.3.0

A powerful, agentic, and human-readable automation framework that allows you to write test cases and reusable libraries in Markdown. Powered by Playwright (Async) and Python, it features Natural Language Processing (NLP), Smart Locators with Self-Healing, and Intelligent Error Detection.

🚀 Key Features

• Markdown-First: Write tests in simple, readable Markdown files. No coding required for standard scenarios.
• Natural Language Steps: Use plain English powered by Advanced NLP (SpaCy) for deep dependency parsing. Fallbacks to Regex for ultimate stability.
• Decoupled Architecture: Transitioned to an Event-Driven Services model using an EventBus, ensuring high cohesion and low coupling.
• Enterprise Scalability (v2.3.0):
  • 10,000+ Library Support: Hybrid registry with persistent caching (.cache/registry.json)
  • Sub-Second Startups: ~0.05s warm boot regardless of library count (100-250x faster)
  • Parallel Indexing: Multi-core processing for cold boot optimization
  • Keyword Search: Inverted index for intelligent action/page discovery
  • Lazy Loading: Header-only scanning with on-demand full parsing
• Smart Locators:
  • Semantic: Finds elements by Label, Placeholder, Role, or Text.
  • Hybrid NLP Scorer:
    • Synonyms: Understands Submit ≈ Save, Login ≈ Sign In.
    • Fuzzy Matching: Tolerates typos (e.g., Logn matches Login).
  • Structural: Understands "Nav Bar", "Header", "Footer".
  • Intelligent Fallback & Self-Healing: Scans the DOM and scores elements. Automatically heals your .md files with new selectors when UI changes.
• Robust Assertions:
  • Automatic Page Checks: Executes # Assertions defined in Page Objects automatically.
  • Health Checks: Performs visibility "Health Checks" on all child elements in -vv mode.
  • Two-Tier Parallelism: Concurrent verification of child elements (Micro) and batch assertions (Macro) for ~85% faster execution.
• Proactive Error Watcher:
  • Real-time API Monitoring: Detects 4xx/5xx network failures.
  • DOM Error Detection: Automatically captures popups like "Session Expired" or "Unauthorized".
• Data Security: Built-in Data Redaction (Masking) for sensitive information in logs and reports.
• Rich Logging V2 (v2.3.0):
  • 4-Phase Structure: BOOTSTRAPPING → INITIALIZATION → EXECUTING TESTCASES → TEARDOWN
  • Granular Stats: Libraries, Actions, Pages, Keywords, Cache hit/miss rates, Boot time
  • Visual Hierarchy: Section headers, status icons (⚡, ✓, ❌), color-coded output
• Continuum Dashboard: Premium, dark-themed HTML reports with:
  • Dashboard Stats: Instant Pass/Fail/API Error counts and test duration.
  • Interactive Timeline: Expandable steps with status icons and high-res screenshot lightbox.
  • Network Intelligence: Integrated API error table for rapid debugging.

---

📦 Installation

1. Clone the repository:

   git clone <repository-url>cd<repository-name>

2. Set up Virtual Environment (Recommended):

   # Windows (PowerShell)
   py -3.13-m venv .venv
   .venv\Scripts\Activate.ps1

3. Install Dependencies & Models:

   pip install -r requirements.txt
   playwright install chromium
   # Download SpaCy Model
   python -m spacy download en_core_web_sm

---

🏃 Usage

Run a test case using the main.py script. The framework now runs asynchronously via asyncio.

python main.py --testcase <path_to_testcase.md> [options]

Options

• --testcase: (Required) Path to the Markdown test case file.
• --templates: Path to the directory containing reusable libraries (default: templates).
• --project: Project name for the report (default: MyProject).
• --headless: Run in headless mode (default: False). Use true or yes to enable (e.g., in CI/CD).

Example

python main.py --testcase example/testcase/login_valid.md --templates example/library --headless false

---

📝 Writing Test Cases

Test cases are Markdown files that define what to test. They focus on the high-level flow.

Structure

A test case file consists of several sections:

1. Metadata: Key-value pairs defining the test (Priority, Tags, Owner).
2. Testcase: The title/objective of the test.
3. Browser Configuration: Settings for the browser (Permissions, Geolocation).
4. Variables: Define test data. Supports dynamic generation.
5. Steps: Numbered list of actions to execute.
6. Expected Result: List of verifications to perform.
7. Post-conditions: Cleanup or final actions.

Example (login_valid.md)

# Metadata
type: flow
priority: P0
tags:
- Login
# Testcase
Verify login with valid credentials
# Browser Configuration- Permissions:
- Geolocation: "12.9716, 77.5946"
# Variables- url: "https://example.com"
- user: "admin"
- pass: "password123"
# Dynamic variable example- new_email: "{{$random.email}}"
# Steps1. Navigate to {{url}}
2. Perform Login with {{user}}::{{pass}}
3. Wait for url to contain "dashboard"
# Expected Result- Verify "Welcome User" is visible

---

📚 Writing Reusable Libraries

Libraries are Markdown files that define how to perform specific actions or interact with specific pages. They allow you to encapsulate logic and reuse it.

Structure

1. Action Executor: The phrase that triggers this library from a Test Case.
2. Locators (Page Identifier): Define explicit selectors for elements (optional but recommended for stability).
3. Steps: The sequence of low-level actions.
4. Variables: Input variables for the action.

Example (login.md) - Action Executor

This library handles the "Perform Login" action.

# Metadata
type: scenario
147: # Action Executor
148: - Perform Login
149: 150: # Page Link (New)
151: # Explicitly links this Action to a Page Object file (e.g. login_page.md)
152: # This ensures the Action uses the Page's locators (like 'user_field')
153: - page: Login Page
# Page Identifier# Define explicit selectors here. The framework will try these first.- user_field: "#username"
- pass_field: "#password"
- login_btn: "button[type='submit']"
# Variables# Map input arguments to local variables- username: {{scenario.user}}
- password: {{scenario.pass}}
# Steps1. Fill "user_field" with value "${username}"
2. Fill "pass_field" with value "${password}"
3. Click "login_btn"

Usage in Test Case

If you have the above library, you can write this in your test case:

2. Perform Login with admin::password123

The framework matches "Perform Login", passes admin as scenario.user and password123 as scenario.pass, and executes the steps defined in the library.

Example (dashboard.md) - Page Verification

This library represents a Page Object. It defines the structure and health checks for a page.

# Metadata
type: page
tags:
- Dashboard
# Action Executor- Verify Dashboard Page
# Page Elements# Supports indentation for hierarchy (Parent > Child)- navigation_sidebar: "//div[@id='sidebar']"
- dashboard_menu: "//a[text()='Dashboard']"
- settings_menu: "//a[text()='Settings']"
- profile_button: "#user-profile"
# Assertions- navigation_sidebar is visible
- profile_button is visible
# CriticalElements# If these fail, the test stops immediately- navigation_sidebar

Usage in Test Case

3. Verify Dashboard Page

The framework loads dashboard.md, finds the "navigation_sidebar" (and automatically verifies its children "dashboard_menu" and "settings_menu" first), then checks "profile_button".

---

🧠 Smart Locators & NLP

The framework understands natural language. You don't always need explicit selectors.

• Click: Click "Submit", Click "Profile Icon", Click "Save Button"
• Fill: Fill "Username" with "john", Fill "Search" with "laptop"
• Navigate: Navigate to https://google.com
• Wait: Wait for 5s, Wait for network-idle, Wait for url to contain "home"
• Verify: Verify "Success Message" is visible

How it works

1. Explicit: Checks Page Identifier section in your library.
2. Semantic: Looks for Accessibility Roles (Button, Link, Heading), Labels, and Placeholders matching the text.
3. Structural: Identifies "Nav Bar", "Header", "Footer".
4. Intelligent Fallback: Scans the DOM for interactive elements and scores them based on your description.
5. Self-Healing: If the Intelligent Fallback finds the element, it updates your Markdown file with the working selector to make future runs faster.

---

🎲 Data Generation

Use the {{$random...}} syntax in your Variables section to generate dynamic data.

• {{$random.email}}: Generates a random email.
• {{$random.name}}: Generates a random full name.
• {{$random.address}}: Generates a random address.
• {{$random.phone_number}}: Generates a random phone number.
• {{$random.uuid}}: Generates a UUID.
• {{$random.int(10, 99)}}: Generates a random integer between 10 and 99.

---

📂 Directory Structure

• framework/: Core framework code (Runner, Parser, NLP, Locator, etc.).
• templates/ (or your custom folder): Contains your reusable libraries (.md files).
• reports/: Generated HTML reports and screenshots.
• main.py: Entry point script (Async).

---

🤝 Contributing

We welcome contributions! Please read our Contribution Guidelines for details on setting up the development environment, understanding the architecture, and coding standards.

---