layoutlens 1.0.0__tar.gz

layoutlens-1.0.0/.github/workflows/release.yml

@@ -0,0 +1,114 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+    
+    - name: Set up Python
+      uses: actions/setup-python@v4
+      with:
+        python-version: '3.10'
+        
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install -e .
+        pip install pytest pytest-cov playwright beautifulsoup4 pyyaml
+        playwright install chromium
+        
+    - name: Run tests
+      run: |
+        pytest tests/ -v --cov=layoutlens --cov-report=term-missing
+      env:
+        OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY_TEST }}
+
+  build:
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+    
+    - name: Set up Python
+      uses: actions/setup-python@v4
+      with:
+        python-version: '3.10'
+        
+    - name: Install build dependencies
+      run: |
+        python -m pip install --upgrade pip build twine
+        
+    - name: Build package
+      run: |
+        python -m build
+        
+    - name: Check package
+      run: |
+        twine check dist/*
+        
+    - name: Upload artifacts
+      uses: actions/upload-artifact@v3
+      with:
+        name: dist
+        path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/')
+    environment:
+      name: pypi
+      url: https://pypi.org/project/layoutlens/
+    permissions:
+      id-token: write
+    steps:
+    - name: Download artifacts
+      uses: actions/download-artifact@v3
+      with:
+        name: dist
+        path: dist/
+        
+    - name: Publish to PyPI
+      uses: pypa/gh-action-pypi-publish@release/v1
+
+  create-release:
+    needs: publish
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+    
+    - name: Create Release
+      uses: actions/create-release@v1
+      env:
+        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      with:
+        tag_name: ${{ github.ref_name }}
+        release_name: Release ${{ github.ref_name }}
+        body: |
+          ## Changes in this Release
+          
+          This release includes updates to the LayoutLens AI-enabled UI testing framework.
+          
+          ### Installation
+          ```bash
+          pip install layoutlens==${{ github.ref_name }}
+          ```
+          
+          ### Quick Start
+          ```python
+          from layoutlens import LayoutLens
+          
+          tester = LayoutLens()
+          result = tester.test_page("page.html", queries=["Is the layout responsive?"])
+          print(f"Success rate: {result.success_rate:.2%}")
+          ```
+          
+          See the [documentation](https://github.com/layoutlens/layoutlens) for more details.
+        draft: false
+        prerelease: ${{ contains(github.ref_name, 'alpha') || contains(github.ref_name, 'beta') || contains(github.ref_name, 'rc') }}

layoutlens-1.0.0/.github/workflows/test.yml

@@ -0,0 +1,125 @@
+name: Test Suite
+
+on:
+  push:
+    branches: [ main, develop ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ['3.10', '3.11', '3.12']
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v4
+      with:
+        python-version: ${{ matrix.python-version }}
+
+    - name: Cache pip dependencies
+      uses: actions/cache@v3
+      with:
+        path: ~/.cache/pip
+        key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements*.txt', '**/setup.py') }}
+        restore-keys: |
+          ${{ runner.os }}-pip-
+
+    - name: Install system dependencies
+      run: |
+        sudo apt-get update
+        sudo apt-get install -y xvfb
+
+    - name: Install Python dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install -e .
+        pip install pytest pytest-cov pytest-mock pytest-xdist
+        pip install playwright beautifulsoup4 pyyaml
+
+    - name: Install Playwright browsers
+      run: |
+        playwright install chromium
+        
+    - name: Run unit tests
+      run: |
+        xvfb-run -a pytest tests/unit/ -v --cov=layoutlens --cov=framework --cov=screenshot --cov=scripts --cov-report=xml --cov-report=term-missing
+      env:
+        OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY_TEST }}
+
+    - name: Run integration tests
+      run: |
+        xvfb-run -a pytest tests/integration/ -v -m "not slow" --maxfail=5
+      env:
+        OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY_TEST }}
+        
+    - name: Upload coverage reports to Codecov
+      uses: codecov/codecov-action@v3
+      with:
+        file: ./coverage.xml
+        fail_ci_if_error: false
+
+  test-package:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+    
+    - name: Set up Python
+      uses: actions/setup-python@v4
+      with:
+        python-version: '3.10'
+        
+    - name: Test package installation
+      run: |
+        python -m pip install --upgrade pip build twine
+        python -m build
+        pip install dist/*.whl
+        python -c "import layoutlens; print('Package installed successfully')"
+        
+    - name: Test CLI
+      run: |
+        layoutlens --help
+        layoutlens generate config --output test_config.yaml
+        layoutlens validate --config test_config.yaml
+
+  test-examples:
+    runs-on: ubuntu-latest
+    if: github.event_name == 'pull_request'
+    steps:
+    - uses: actions/checkout@v4
+    
+    - name: Set up Python
+      uses: actions/setup-python@v4
+      with:
+        python-version: '3.10'
+        
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install -e .
+        pip install playwright beautifulsoup4 pyyaml
+        playwright install chromium
+        
+    - name: Test example configurations
+      run: |
+        python -c "
+        import yaml
+        with open('examples/layoutlens_config.yaml', 'r') as f:
+            config = yaml.safe_load(f)
+        print('Config validation: OK')
+        
+        with open('examples/sample_test_suite.yaml', 'r') as f:
+            suite = yaml.safe_load(f)
+        print('Test suite validation: OK')
+        "
+        
+    - name: Validate example code syntax
+      run: |
+        python -m py_compile examples/basic_usage.py
+        python -m py_compile examples/advanced_usage.py
+        python -m py_compile examples/ci_cd_integration.py
+        echo "All example files compile successfully"

layoutlens-1.0.0/CHANGELOG.md

@@ -0,0 +1,105 @@
+# Changelog
+
+All notable changes to the LayoutLens project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- Enhanced LayoutLens framework with modern Python API
+- CLI interface with comprehensive commands (`layoutlens`)
+- Multi-viewport screenshot testing across desktop, tablet, and mobile
+- Intelligent test query generation from HTML DOM analysis
+- Comprehensive test suite orchestration with YAML configuration
+- Benchmark generation system with systematic HTML templates
+- Advanced screenshot management with context managers
+- Configuration management with hierarchical settings (files, env vars, params)
+- Package distribution setup with proper entry points
+- Comprehensive testing framework with mocked dependencies
+- CI/CD pipelines for automated testing and release
+- Complete documentation structure with user guides and API references
+
+### Changed
+- **BREAKING**: Reorganized project structure with clear separation
+  - Moved original components to `legacy/` directory
+  - Moved benchmark data to `benchmarks/` directory  
+  - Moved HTML samples to `tests/fixtures/sample_pages/legacy_samples/`
+  - Enhanced framework now in `layoutlens/` package
+  - Testing engine in `scripts/testing/`
+  - Benchmark tools in `scripts/benchmark/`
+- Updated all import paths and references to new structure
+- Enhanced error handling with graceful degradation
+- Improved API design with backward compatibility maintained
+
+### Enhanced
+- Original `LayoutLens.ask()` and `compare_layouts()` methods preserved for compatibility
+- Extended API with new methods:
+  - `test_page()` - Comprehensive page testing with auto-generated queries
+  - `compare_pages()` - Visual comparison with structured results
+  - `run_test_suite()` - Execute organized test suites
+  - `generate_benchmark_data()` - Create systematic test datasets
+
+### Infrastructure
+- GitHub Actions workflows for testing across Python 3.8-3.12
+- Automated package building and PyPI publishing
+- Code coverage reporting with Codecov integration
+- Example validation in CI/CD pipeline
+- Comprehensive test fixtures and mock strategies
+
+## [0.1.0] - Initial Release
+
+### Added
+- Basic LayoutLens framework for AI-powered UI testing
+- Screenshot capture using Playwright
+- OpenAI vision model integration for natural language queries
+- CSV-based benchmark system
+- HTML test samples for various UI patterns
+- Simple benchmark runner for automated testing
+
+### Core Features
+- `framework.py` - Original LayoutLens class
+- `screenshot.py` - HTML to image conversion
+- `benchmark_runner.py` - CSV-driven test execution
+- Support for single image tests and pairwise comparisons
+- Natural language query interface for UI validation
+
+---
+
+## Migration Guide
+
+### From v0.1.0 to v1.0.0
+
+**File Locations:**
+- `framework.py` → `legacy/framework.py` 
+- `screenshot.py` → `legacy/screenshot.py`
+- `benchmark_runner.py` → `legacy/benchmark_runner.py`
+- `benchmark.csv` → `benchmarks/benchmark.csv`
+- `html/` samples → `tests/fixtures/sample_pages/legacy_samples/`
+
+**Usage Changes:**
+```python
+# Old usage (still supported)
+from legacy.framework import LayoutLens
+lens = LayoutLens(api_key="key")
+result = lens.ask(["image.png"], "Question?")
+
+# New recommended usage
+from layoutlens import LayoutLens
+tester = LayoutLens(api_key="key")
+result = tester.test_page("page.html", queries=["Question?"])
+```
+
+**Command Line:**
+```bash
+# Old
+python benchmark_runner.py
+
+# New
+python legacy/benchmark_runner.py
+# Or use enhanced CLI
+layoutlens test --page page.html
+```
+
+All legacy interfaces remain functional for backward compatibility.

layoutlens-1.0.0/CLAUDE.md

@@ -0,0 +1,164 @@
+# CLAUDE.md - LayoutLens v1.0.0
+
+This file provides guidance to Claude Code (claude.ai/code) when working with the LayoutLens codebase.
+
+## Project Overview
+
+LayoutLens is a production-ready AI-powered UI testing framework that enables natural language visual testing. It captures screenshots using Playwright and analyzes them with OpenAI's GPT-4o Vision API to validate layouts, accessibility, responsive design, and visual consistency.
+
+**Key Achievement:** 95.2% accuracy on professional ground truth benchmark suite.
+
+## Quick Start Commands
+
+### Installation
+```bash
+pip install -e .
+playwright install
+```
+
+### Basic Usage
+```bash
+# Set API key
+export OPENAI_API_KEY="your_key_here"
+
+# Test a single page
+python -c "
+from layoutlens import LayoutLens
+tester = LayoutLens()
+result = tester.test_page('benchmarks/ecommerce_product.html', 
+                         queries=['Is the navigation properly aligned?'])
+print(f'Success rate: {result.success_rate:.1%}')
+"
+
+# Run ground truth benchmark evaluation
+python scripts/testing/ground_truth_evaluator.py --output-report results.json
+```
+
+### CLI Usage
+```bash
+layoutlens --help
+```
+
+## Release v1.0.0 Architecture
+
+### Core Package Structure
+- **`layoutlens/core.py`**: Main LayoutLens class with user-friendly API
+- **`layoutlens/config.py`**: Configuration management (YAML + env vars)
+- **`layoutlens/cli.py`**: Command-line interface
+- **`scripts/testing/`**: Testing infrastructure (PageTester, ScreenshotManager, QueryGenerator)
+- **`scripts/benchmark/`**: Benchmark generation tools
+
+### Key Features Implemented
+- ✅ **Multi-viewport screenshot capture** (desktop, mobile, tablet)
+- ✅ **OpenAI GPT-4o Vision integration** for visual analysis
+- ✅ **Ground truth benchmark suite** with objective test cases
+- ✅ **Natural language query processing** 
+- ✅ **Configuration system** with YAML and environment variables
+- ✅ **CLI interface** for automation and CI/CD
+- ✅ **Professional documentation** and examples
+
+## Ground Truth Benchmark Suite
+
+The package includes a comprehensive benchmark with objectively measurable test cases:
+
+### Test Categories (95.2% Overall Accuracy)
+- **Layout Alignment Issues**: 100.0% accuracy (6/6 tests)
+  - Navigation centering (2% offset detection)
+  - Logo positioning (wrong side detection)  
+  - Button alignment (margin inconsistencies)
+
+- **Responsive Design Problems**: 100.0% accuracy (4/4 tests)
+  - Mobile viewport overflow
+  - Touch target sizing (below 44px minimum)
+  - Text readability (below 14px mobile standard)
+
+- **Accessibility (WCAG) Violations**: 100.0% accuracy (6/6 tests)
+  - Missing alt text
+  - Form label associations
+  - Keyboard navigation
+  - Heading hierarchy
+  - Table structure
+  - Color-only information
+
+- **Color Contrast Violations**: 80.0% accuracy (4/5 tests)
+  - WCAG AA compliance (4.5:1 ratio requirements)
+  - Calculated contrast ratios (1.07:1, 1.61:1, 1.92:1, etc.)
+
+### Benchmark Files Location
+- **`benchmarks/ground_truth_tests/`**: Test cases with embedded ground truth metadata
+- **`benchmarks/ground_truth_tests/GROUND_TRUTH_ANSWERS.md`**: Expected answers documentation
+
+## Testing and Development
+
+### Running Tests
+```bash
+# Install test dependencies
+pip install pytest
+
+# Run core functionality tests  
+pytest tests/unit/test_config.py tests/unit/test_core.py -v
+
+# Run ground truth evaluation
+python scripts/testing/ground_truth_evaluator.py
+```
+
+### Example Test Cases
+```python
+from layoutlens import LayoutLens
+
+# Initialize with API key
+tester = LayoutLens(api_key="your_key")
+
+# Test single page
+result = tester.test_page("page.html", queries=[
+    "Is the navigation menu properly aligned?",
+    "Are the button sizes appropriate for mobile?"
+])
+
+# Compare two pages
+comparison = tester.compare_pages("before.html", "after.html")
+print(comparison['answer'])
+```
+
+## Package Structure (Post-Cleanup)
+
+```
+layoutlens/
+├── layoutlens/           # Core package
+│   ├── core.py          # Main LayoutLens class  
+│   ├── config.py        # Configuration system
+│   └── cli.py           # Command line interface
+├── scripts/             # Testing utilities
+│   ├── testing/         # Page testing infrastructure
+│   └── benchmark/       # Benchmark generation
+├── benchmarks/          # HTML test files + ground truth
+├── docs/               # Documentation
+├── examples/           # Usage examples
+└── tests/              # Test suite
+```
+
+## Performance Characteristics
+
+- **Processing Time**: ~23 seconds average per test
+- **Accuracy**: 95.2% on objective ground truth benchmark
+- **Package Size**: ~50MB (cleaned from 300MB+ development version)
+- **Dependencies**: OpenAI, Playwright, BeautifulSoup4, PyYAML, Pillow
+- **Python Compatibility**: 3.8+
+
+## Development Notes
+
+### What Was Removed for v1.0.0 Release
+- ❌ Legacy framework files (moved to clean v1.0 API)
+- ❌ Development virtual environments (~200MB)
+- ❌ Test output files and screenshots (~50MB)
+- ❌ Build artifacts and caches (~5MB)
+- ❌ Development-specific .md files
+
+### What Was Fixed
+- ✅ OpenAI Vision API integration in PageTester
+- ✅ Screenshot capture using Playwright
+- ✅ Ground truth evaluation system
+- ✅ Package dependencies and structure
+- ✅ Configuration and CLI systems
+
+This codebase is release-ready with professional-grade accuracy measurement and comprehensive documentation.

layoutlens-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Gaurav Sood
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

layoutlens-1.0.0/MANIFEST.in

@@ -0,0 +1,41 @@
+# Include important documentation files
+include README.md
+include LICENSE
+include CLAUDE.md
+include CHANGELOG.md
+
+# Include configuration files
+include *.toml
+include *.ini
+include *.cfg
+include requirements*.txt
+include Makefile
+
+# Include test files and fixtures
+recursive-include tests *.py
+recursive-include tests/fixtures *.html *.json *.yaml *.yml
+
+# Include example files
+recursive-include examples *.py *.yaml *.yml *.html *.md
+
+# Include documentation
+recursive-include docs *.md *.rst *.txt
+
+# Include template files
+recursive-include scripts/benchmark/templates *.html *.css *.js
+
+# Include GitHub workflows
+recursive-include .github/workflows *.yml *.yaml
+
+# Exclude unnecessary files
+global-exclude *.pyc
+global-exclude *.pyo
+global-exclude *.pyd
+global-exclude __pycache__
+global-exclude .DS_Store
+global-exclude .coverage
+global-exclude htmlcov
+global-exclude .pytest_cache
+global-exclude *.egg-info
+global-exclude build
+global-exclude dist