Contributing to Scrapazoid

Thank you for considering contributing to Scrapazoid! This document provides guidelines for contributions.

Getting Started

1. Fork the repository
2. Clone your fork: git clone https://github.com/yourusername/scrapazoid.git
3. Create a branch: git checkout -b feature/your-feature-name
4. Make your changes
5. Test your changes
6. Commit: git commit -m "Add feature: description"
7. Push: git push origin feature/your-feature-name
8. Open a Pull Request

Development Setup

# Create virtual environment
python -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt
pip install -r docs-requirements.txt

# Install Playwright browsers
playwright install chromium

# Initialize database
flask init_db

# Run in development mode
python run.py

Code Style

Python

• Follow PEP 8
• Use type hints where appropriate
• Add docstrings to functions and classes
• Keep functions focused and small

Example:

def process_execution(execution_id: int) -> Dict[str, Any]:
    """
    Process a script execution.

    Args:
        execution_id: ID of the execution to process

    Returns:
        Dictionary with execution results
    """
    # Implementation
    pass

JavaScript

• Use ES6+ features
• Use descriptive variable names
• Add comments for complex logic

Templates

• Use semantic HTML
• Keep inline styles minimal
• Add appropriate ARIA labels

Testing

Running Tests

# Run all tests
pytest

# Run with coverage
pytest --cov=app

# Run specific test file
pytest tests/test_sandbox.py

Writing Tests

def test_script_validation():
    """Test that dangerous scripts are rejected"""
    validator = ScriptValidator()

    dangerous_code = "import os; os.system('rm -rf /')"
    is_valid, error = validator.validate(dangerous_code)

    assert not is_valid
    assert "Forbidden import" in error

Documentation

Writing Documentation

• Use clear, concise language
• Include code examples
• Add screenshots where helpful
• Update navigation in mkdocs.yml

Building Documentation Locally

# Install dependencies
pip install -r docs-requirements.txt

# Serve locally
mkdocs serve

# Build static site
mkdocs build

Visit http://127.0.0.1:8000 to preview.

Pull Request Guidelines

Before Submitting

• Code follows style guidelines
• Tests pass
• Documentation updated
• Commit messages are clear
• Branch is up to date with main

PR Description

Include:

1. What - What does this PR do?
2. Why - Why is this change needed?
3. How - How does it work?
4. Testing - How was it tested?

Example:

## What
Adds automatic screenshot capture on scroll events

## Why
Users want to see page state after scrolling during script execution

## How
- Added scroll event listener using Playwright page.on('scroll')
- Debounces scroll events to avoid too many screenshots
- Tracks pending screenshot tasks

## Testing
- Tested with script that scrolls through long pages
- Verified screenshots appear in execution history
- Confirmed no performance degradation

Feature Requests

Have an idea? Open an issue with:

• Clear description of the feature
• Use case / problem it solves
• Proposed solution (if any)
• Examples

Bug Reports

Found a bug? Open an issue with:

• Title: Short, descriptive summary
• Description: What happened vs. what you expected
• Steps to Reproduce: Numbered steps
• Environment: OS, Python version, browser
• Logs: Relevant error messages
• Screenshots: If applicable

Template:

**Bug Description**
Execution hangs when clicking dynamic elements

**Steps to Reproduce**
1. Create script that clicks element loaded via AJAX
2. Run script
3. Observe execution hangs at click operation

**Expected Behavior**
Script should click element and continue

**Actual Behavior**
Execution hangs and eventually times out

**Environment**
- OS: Ubuntu 22.04
- Python: 3.11.2
- Browser: Chromium (Playwright)

**Logs**
[Navigation] Navigated to: https://example.com
[Script] About to click button
(hangs here)

**Additional Context**
Element appears after 2-second delay via AJAX

Areas for Contribution

High Priority

• Additional example scripts
• Performance optimizations
• Error handling improvements
• Test coverage

Documentation

• Video tutorials
• More examples
• Troubleshooting guides
• API documentation

Features

• Script scheduling/cron
• Email notifications
• Export execution data
• Shared script library
• Multi-browser support

Code Review Process

1. Maintainer reviews PR
2. Feedback provided via comments
3. Changes requested if needed
4. Approval given
5. PR merged to main
6. Deployed in next release

Questions?

• Open a Discussion on GitHub
• Check existing Issues
• Review documentation

License

By contributing, you agree that your contributions will be licensed under the same license as the project.