🚀 QA Hub Framework

The Precision Engineering Core for Automated Quality Assurance

A premium, ultra-professional BDD engine architected for mission-critical validation.

---

✨ Key Features

• 🏗️ Page Object Model (POM): Standardized structure for UI testing using a robust BasePage.
• 🛠️ Dedicated CLI Tool (qa-hub): Simplified test execution with environmental and tag overrides.
• 🪵 Contextual Logger: Professional, colorized logs with automatic Feature/Scenario context.
• 🛡️ Security Sanity Checks: Built-in steps for API header hygiene and cookie security validation.
• 🎭 Dual-Driver Engine: Native support for both Selenium and Playwright, switchable via configuration.
• 🎨 Visual Regression Engine: RMS-based image comparison with automated baseline management.
• ⚙️ Surgical Lifecycle Management: Advanced driver reuse logic to optimize execution speed.
• 🧪 CI/CD Orchestration: Seamless integration with GitHub Actions and detailed audit logs.

---

📖 Documentation

Check out our professional Documentation Site for detailed guides on API, GUI, and PDF testing.

---

🏗️ Architecture Overview

The framework follows a modular architecture to ensure separation of concerns:

graph TD
    A[Test Features / Gherkin] --> B[Step Definitions]
    B --> C[Page Objects]
    C --> D[qa_framework.core.BasePage]
    D --> E[Selenium WebDriver]
    B --> F[qa_framework.utils.DriverFactory]

Loading

For more details on our core components, see ARCHITECTURE.md.
For the full list of reusable Gherkin steps, see STEPS.md.
For information on our CI/CD pipelines, see .github/workflows/README.md.

---

🚀 Quick Start

1. Installation

Add the framework to your requirements.txt:

-e git+https://github.com/carlos-camara/qa-hub-framework.git#egg=qa-automation-framework

Then install dependencies:

pip install -r requirements.txt
# Verify the CLI tool
qa-hub --help

2. Basic Execution

Run your tests using the dedicated CLI tool:

# Run all smoke tests in staging
qa-hub run --env staging --tags smoke

---

🛠️ Configuration Manager

The framework uses a centralized configuration system (features/config/config.yaml) that supports environment overrides (staging, prod) and secret management (.env).

For a detailed setup guide and advanced usage, see Configuration Guide.

---

🛠️ Command Line Interface (qa-hub)

The framework provides a powerful CLI to manage your test runs efficiently.

qa-hub run [OPTIONS]

Option	Description
--env	Set execution environment (local, dev, staging, prod)
--tags	Filter by Gherkin tags (e.g., @smoke)
--browser	Override browser (chrome, firefox, playwright)
--fail	Stop execution on the first failure
--no-capture	Show real-time logs and prints
--junit-dir	Directory for JUnit XML reports

For more details, see the CLI Guide.

---

🪵 Contextual Logging

Every execution is enriched with a high-fidelity audit trail.

• Automatic Context: Logs automatically include [Feature | Scenario] names.
• Colorized Output: Visual differentiation between INFO, SUCCESS, WARNING, and ERROR.
• Timestamps: Precision timing for every action.

See Logging Documentation for configuration and usage.

---

🛡️ Security Sanity Checks

Validate your API security posture with built-in audit steps.

• Metadata Leaks: Detect if your server leaks technology versions.
• Security Headers: Verify presence of HSTS, CSP, and X-Frame-Options.
• Cookie Security: Audit session cookies for Secure, HttpOnly, and SameSite flags.

Check the Security Guide for implementation details.

---

🎨 Visual Regression Testing

The framework includes a professional-grade image comparison engine.

• Baseline Management: Missing baselines are automatically seeded during the first run.
• RMS Error Calculation: High-fidelity detection of layout shifts and CSS glitches.
• Agnostic Logic: Works identically across Selenium and Playwright backends.

Then the "stats grid" element should visually match the baseline image "dashboard_stats" with a 5.0% tolerance

---

⚡ Global Step Registry

The framework provides an extensive library of modular Gherkin steps across all testing layers, reducing project-specific boilerplate.

🔌 API Validation

• Then the response JSON path "{path}" should equal "{expected}" (Alias for precision matching)
• Then the response JSON path "{path}" should be a "{py_type}" (Type-safe assertions)

📄 Intelligent PDF Audit

• Then I verify the content of the first {count:d} pages of "{filename}" (Non-empty extraction check)
• Then the PDF "{filename}" should have at least {page_count:d} pages

🏗️ Foundation & Stability

• And I wait for "{name}" to be stable (Generic animation/load placeholder)
• When I store the text of the "{element_name}" as "{var_name}" (Dynamic data extraction)

🎨 Masked Visual Comparison

• Then the "{desc}" page should visually match the baseline image "{name}" without elements and with a {threshold:f}% tolerance (Allows blacking out dynamic elements like charts or dates to prevent false positives).

---

🎭 Playwright Integration

The framework supports Playwright as an alternative to Selenium, offering faster execution and better stability for modern web apps.

Installation

After installing requirements, run the Playwright browser installer:

pip install -r requirements.txt
playwright install

Note

The playwright install command downloads browser binaries. For CI environments, you may need to run playwright install-deps first.

Configuration

To use Playwright instead of Selenium, configure features/config/properties.cfg or config.yaml:

Driver:
  web_library: playwright
  type: chrome
  headless: true

Supported Browsers

Browser	Selenium	Playwright
Chrome	✅	✅
Firefox	✅	✅
Edge	✅	✅
WebKit	❌	✅

Tip

WebKit is the engine behind Safari. Use it for cross-browser testing without macOS.

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

---