Home / Contribute

Contributing to WiFi Jammer

Thank you for your interest in contributing to WiFi Jammer! This guide will help you get started with development and make your first contribution.

Development Setup

1. Clone the Repository

git clone https://github.com/oyi77/wifi-jammer.git
cd wifi-jammer

2. Create a Virtual Environment

python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install Dependencies

# Install base dependencies
pip install -r requirements.txt

# Install development dependencies
pip install -r requirements-optional.txt

# Install in development mode
pip install -e .

4. Install Development Tools

pip install pytest pytest-cov flake8 black isort
Note: For macOS users, run bash install.sh or bash quick_install.sh to automatically set up Location Services permissions.

Code Style Guidelines

WiFi Jammer follows strict code quality standards to ensure maintainability and readability.

Python Best Practices

Code Structure

Naming Conventions

Example: Adding a New Function

def scan_networks(interface: str, channel: int = None) -> List[Network]:
    """
    Scan for available WiFi networks on the specified interface.
    
    Args:
        interface: The wireless interface name (e.g., 'en0', 'wlan0')
        channel: Optional channel number to scan. If None, scans all channels.
    
    Returns:
        List of Network objects representing discovered networks.
    
    Raises:
        NetworkError: If scanning fails or interface is invalid.
    
    Example:
        >>> networks = scan_networks('en0', channel=6)
        >>> print(f"Found {len(networks)} networks")
    """
    # Implementation here
    pass

Architecture Overview

WiFi Jammer follows SOLID principles and uses design patterns for clean, maintainable code.

SOLID Principles

Design Patterns

File Structure

wifi_jammer/
├── core/              # Core interfaces and data structures
│   ├── interfaces.py  # Attack types, configs, network models
│   └── platform_interface.py  # Platform abstraction
├── scanner/           # Network scanning functionality
│   └── network_scanner.py
├── attacks/           # Attack strategy implementations
│   ├── base_attack.py
│   ├── deauth_attack.py
│   └── flood_attacks.py
├── factory/           # Factory pattern for creating attacks
│   └── attack_factory.py
├── utils/             # Utility functions and logging
│   ├── logger.py
│   ├── validators.py
│   └── platform_utils.py
├── gui/               # Qt GUI components
├── cli.py             # Command-line interface
└── tui.py             # Text user interface

Adding New Attack Types

To add a new attack type, follow these steps:

1. Create Attack Class

Create a new file in wifi_jammer/attacks/:

from wifi_jammer.attacks.base_attack import BaseAttack
from scapy.all import Packet

class MyCustomAttack(BaseAttack):
    """Custom attack implementation."""
    
    def _create_packet(self) -> Packet:
        """
        Create the attack packet.
        
        Returns:
            Scapy packet for the attack.
        """
        # Implement packet creation logic
        pass

2. Register in AttackFactory

Add your attack to wifi_jammer/factory/attack_factory.py:

from wifi_jammer.attacks.my_custom_attack import MyCustomAttack

# In AttackFactory class
def _register_attacks(self):
    self._attacks = {
        AttackType.DEAUTH: DeauthAttack,
        AttackType.MY_CUSTOM: MyCustomAttack,  # Add your attack
        # ... other attacks
    }

3. Add Attack Type Enum

Add the new attack type to wifi_jammer/core/interfaces.py:

class AttackType(Enum):
    DEAUTH = "deauth"
    DISASSOC = "disassoc"
    MY_CUSTOM = "my_custom"  # Add your attack type
    # ... other types

4. Write Tests

Create tests in tests/test_attacks.py:

def test_my_custom_attack():
    """Test custom attack creation and execution."""
    factory = AttackFactory()
    attack = factory.create_attack(AttackType.MY_CUSTOM)
    # Add test assertions
    assert attack is not None

Testing Requirements

All code must be thoroughly tested before submission.

Coverage Target

Running Tests

# Run all tests
pytest

# Run with coverage
pytest --cov=wifi_jammer --cov-report=html

# Run specific test file
pytest tests/test_attacks.py

# Run with verbose output
pytest -v

Test Organization

Example Test

import pytest
from unittest.mock import Mock, patch
from wifi_jammer.attacks.deauth_attack import DeauthAttack
from wifi_jammer.core.interfaces import AttackConfig, AttackType

def test_deauth_attack_creation():
    """Test deauth attack can be created."""
    attack = DeauthAttack()
    assert attack is not None
    assert attack.attack_type == AttackType.DEAUTH

@patch('scapy.all.sendp')
def test_deauth_attack_execution(mock_sendp):
    """Test deauth attack execution."""
    config = AttackConfig(
        attack_type=AttackType.DEAUTH,
        target_bssid="00:11:22:33:44:55",
        interface="wlan0",
        count=10
    )
    attack = DeauthAttack()
    result = attack.execute(config)
    assert result is True
    assert mock_sendp.called

Code Quality Tools

Linting

# Run flake8
flake8 wifi_jammer/

# Run with specific rules
flake8 wifi_jammer/ --max-line-length=88

Formatting

# Format code with black
black wifi_jammer/

# Check formatting without changes
black --check wifi_jammer/

# Sort imports
isort wifi_jammer/

Type Checking

# Run mypy (if installed)
mypy wifi_jammer/

Pull Request Process

1. Create a Branch

git checkout -b feature/my-new-feature
# or
git checkout -b fix/bug-description

2. Make Your Changes

3. Commit Your Changes

git add .
git commit -m "Add feature: description of changes"
# Use clear, descriptive commit messages

4. Run Tests and Linters

# Run tests
pytest

# Check code style
black --check wifi_jammer/
flake8 wifi_jammer/

# Check coverage
pytest --cov=wifi_jammer --cov-report=term

5. Push and Create Pull Request

git push origin feature/my-new-feature

Then create a pull request on GitHub with:

6. Code Review

Your PR will be reviewed for:

Code Review Checklist

Before submitting a PR, ensure:

Reporting Issues

Found a bug or have a feature request? Please create an issue on GitHub.

Bug Reports

Include the following information:

Feature Requests

Describe:

Create Issue on GitHub

Getting Help

Need help getting started or have questions?

License

By contributing to WiFi Jammer, you agree that your contributions will be licensed under the MIT License.