# BeEF Test Suite

This directory contains the BeEF test suite using RSpec and SimpleCov for comprehensive testing and coverage reporting.

## Setup

### Prerequisites
- Ruby 3.0+
- Bundler
- All gems from `Gemfile`

### Configuration Files
- `spec/spec_helper.rb` - Main test configuration
- `.simplecov` - Coverage configuration
- `spec/support/` - Test helpers and utilities

## Running Tests

### Basic Commands

```bash
# Run all tests (fast, no coverage)
bundle exec rake short
# or
bundle exec rspec spec/ --tag '~run_on_browserstack' --tag '~run_on_long_tests'

# Run specific component tests
bundle exec rspec spec/beef/core/
bundle exec rspec spec/beef/extensions/
bundle exec rspec spec/beef/modules/
```

### Coverage Commands

```bash
# Complete coverage (recommended)
bundle exec rake coverage
# or
COVERAGE=all bundle exec rspec spec/ --tag '~run_on_browserstack' --tag '~run_on_long_tests'

# Component-specific coverage
bundle exec rake coverage_core        # Core only
bundle exec rake coverage_modules     # Modules only
bundle exec rake coverage_extensions  # Extensions only
```

### Legacy Commands (Still Supported)

```bash
# Old coverage commands still work
bundle exec rake coverage:modules
bundle exec rake coverage:all
bundle exec rake coverage_complete
```

## Architecture

### SimpleCov Configuration

- **Environment-based**: Uses `COVERAGE=core|modules|extensions|all` environment variable
- **Grouped reporting**: Separate groups for Core, Extensions, and Modules
- **Filtered tracking**: Only tracks relevant files based on focus area
- **HTML reports**: Generated in `coverage/` directory

### Test Organization

- **Centralized config**: `BeefTestConfig` module provides test data instead of global constants
- **Component isolation**: Each component (core/extensions/modules) has dedicated specs
- **Branch coverage**: Realistic test data for conditional logic testing
- **Mock management**: Proper mocking of external dependencies

### Rake Tasks

- **Clean separation**: Base `spec*` tasks vs coverage `coverage*` tasks
- **Environment variables**: Coverage controlled via `COVERAGE` env var
- **No sequential execution**: Single test runs with proper filtering
- **Backward compatibility**: Old task names still work

## Key Improvements

### ✅ **Eliminated Global Constant Collisions**
- Branch-coverage data for the dynamic module spec loaders lives in
  `BeefTestConfig.branch_coverage_for(:component)` (in `spec/spec_helper.rb`).
- Each module spec file pulls its own component (`:browser`, `:exploits`, `:host`,
  `:misc`, `:network`, `:social_engineering`) into a uniquely-named local
  constant (e.g. `BRANCH_COVERAGE_HOST`), so loading the full suite no longer
  triggers "already initialized constant" warnings or silently overwrites data.

### ✅ **Simplified Coverage Logic**
- Cleaner filtering using `track_files` instead of complex `add_filter` logic
- Environment variable `COVERAGE` instead of `COVERAGE_FOCUS`

### ✅ **Better Test Organization**
- Centralized test configuration in `BeefTestConfig`
- Component-specific test data loading
- Reduced code duplication

### ✅ **Cleaner Rake Tasks**
- Single execution instead of sequential runs
- Proper environment variable usage
- Backward compatibility maintained

### ✅ **Standard Patterns**
- Uses `.simplecov` config file (standard practice)
- Follows RSpec best practices
- Better separation of concerns

## Module Spec Pattern (dynamic loaders)

Specs under `spec/beef/modules/**/<category>_spec.rb` walk every
`modules/<category>/**/module.rb` file and generate a `RSpec.describe` block per
class. They cover:

- `.options` returns an `Array` (when defined)
- `#pre_send` runs without raising (when defined)
- `#post_execute` runs without raising (when defined)
- An extra `#post_execute` example with a realistic datastore for any module
  listed in `BeefTestConfig.branch_coverage_for(:category)`

Trade-off: this is a coverage-driving baseline. The `expect { ... }.not_to
raise_error` assertion catches load failures, missing constants, nil crashes,
and undefined methods, but it does not assert behavioural correctness. Add
targeted assertions for high-value modules (see the `Wordpress_add_user` and
`Test_get_variable` examples in `spec/beef/modules/misc/misc_spec.rb`).

## Coverage Focus Areas

- **core**: Framework core functionality
- **extensions**: Extension modules
- **modules**: Command modules (main focus)
- **all**: Complete coverage across all areas

## Troubleshooting

### Common Issues

1. **"already initialized constant" warnings**
   - Fixed by using centralized config instead of global constants

2. **Low coverage percentages**
   - Use `COVERAGE=all` for complete coverage
   - Ensure realistic test data triggers conditional paths

3. **Test failures**
   - Check that mocks are properly configured
   - Verify test data matches module expectations

### Debug Commands

```bash
# Run with debug output
bundle exec rspec --format documentation

# Run single test file
bundle exec rspec spec/beef/modules/browser/browser_spec.rb

# Check coverage report
open coverage/index.html
```

## Contributing

When adding new tests:

1. Use `BeefTestConfig.branch_coverage_for(:component)` for branch test data
2. Add realistic datastore values that trigger conditional logic
3. Mock external dependencies (database, network, etc.)
4. Follow existing patterns for consistency