# Intel 400x Common Functionality Tests

This directory contains comprehensive tests for the `intel_400x.rs` common functionality module, which provides shared
timing, clock handling, and bus operations for Intel 400x series chips.

## Test Organization

### Unit Tests (in implementation files)

- **Intel4001 unit tests**: Located in `src/components/memory/intel_4001.rs`
    - Component creation and configuration
    - Memory operations and data loading
    - State management and transitions
    - Error handling and edge cases

### Integration Tests (in tests/ directory)

1. **`lib.rs`** - Test library and common utilities
2. **`intel_400x_tests.rs`** - Tests for the common intel_400x functionality
3. **`intel_4001_state_machine_test.rs`** - Intel 4001 ROM state machine tests
4. **`intel_4002_state_machine_test.rs`** - Intel 4002 RAM state machine tests
5. **`intel_4003_state_machine_test.rs`** - Intel 4003 shift register state machine tests
6. **`intel_4004_state_machine_test.rs`** - Intel 4004 CPU state machine tests
7. **`integration_tests.rs`** - Integration tests with concrete chip implementations
8. **`json_integration_tests.rs`** - JSON system configuration integration tests
9. **`simple_test.rs`** - Working demonstration of core functionality
10. **`gui_tests.rs`** - GUI component tests
11. **`gui_integration_tests.rs`** - GUI integration tests

### Test Categories

#### 1. Common Functionality Tests (`intel_400x_tests.rs`)

- **Timing Constants**: Verify access times and setup requirements
- **Address Assembly**: Test nibble-to-address conversion logic
- **State Machine**: Test state transition logic and queries
- **Clock Edge Detection**: Test edge detection algorithms
- **Data Bus Operations**: Test bit manipulation for 4-bit bus
- **Utility Functions**: Test helper functions and pin operations

#### 2. State Machine Tests (`intel_400x_state_machine_test.rs`)

- **Intel 4001 ROM**: State machine transitions for ROM operations
- **Intel 4002 RAM**: State machine transitions for RAM operations
- **Intel 4003 Shift Register**: State machine transitions for shift register operations
- **Intel 4004 CPU**: State machine transitions for CPU instruction processing

#### 3. Integration Tests (`integration_tests.rs`)

- **Trait Implementation**: Verify concrete types implement traits correctly
- **Cross-Component Compatibility**: Test multiple components work together
- **Real Component Testing**: Test with actual Intel4001 implementation
- **Lifecycle Testing**: Test component initialization and cleanup

#### 4. JSON Configuration Tests (`json_integration_tests.rs`)

- **System Creation**: Test JSON-based system configuration loading
- **Component Wiring**: Verify automatic pin connections from config
- **Multiple Configurations**: Test basic, max, and I/O demo configurations

#### 5. Simple Tests (`simple_test.rs`)

- **Core Functionality**: Demonstrates that the intel_400x module is testable
- **Basic Operations**: Tests fundamental features that work correctly
- **Regression Prevention**: Ensures core functionality remains stable

#### 6. GUI Tests (`gui_tests.rs`, `gui_integration_tests.rs`)

- **GUI Components**: Test GUI component rendering and state
- **GUI Integration**: Test GUI with full system integration

## Running the Tests

### Run All Tests

```bash
cargo test
```

### Run Specific Test Categories

```bash
# Common functionality tests
cargo test intel_400x_tests

# State machine tests
cargo test intel_4001_state_machine_test
cargo test intel_4002_state_machine_test
cargo test intel_4003_state_machine_test
cargo test intel_4004_state_machine_test

# Integration tests
cargo test integration_tests

# JSON configuration tests
cargo test json_integration_tests

# Simple/core tests
cargo test simple_test
```

### Run with Detailed Output

```bash
cargo test -- --nocapture
```

### Run Specific Test

```bash
cargo test test_name
```

## Test Architecture

### Test Infrastructure

The test suite uses the shared test library (`lib.rs`) which provides:

- **Helper functions**: Common test utilities for component creation and configuration
- **Shared assertions**: Reusable assertion patterns for state machine testing
- **Test fixtures**: Pre-configured component setups for common test scenarios

### Integration Testing

Tests verify that:

- Concrete implementations (like Intel4001) correctly use the common traits
- Multiple components can interact through the common interface
- The common functionality works correctly in real usage scenarios

## Key Testing Areas

### 1. Timing and Clock Logic

- Clock edge detection accuracy
- Two-phase clock handling
- Access time simulation
- State machine timing

### 2. Address Handling

- Nibble assembly into full addresses
- Address latching during clock phases
- Address validation and bounds checking

### 3. Data Bus Operations

- 4-bit data bus read/write operations
- Bus tri-stating for contention avoidance
- Bit-level manipulation and verification

### 4. State Machine Verification

- State transition correctness
- State invariant preservation
- Reset behavior verification
- Error state handling

### 5. Hardware Abstraction

- Pin operation safety
- Driver management
- Hardware timing simulation
- Bus contention avoidance

## Adding New Tests

When adding new functionality, add corresponding tests:

1. **Unit tests** for pure functions in `intel_400x_tests.rs`
2. **State machine tests** for component behavior in `intel_400x_state_machine_test.rs`
3. **Integration tests** for concrete usage in `integration_tests.rs`
4. **JSON config tests** for system configuration in `json_integration_tests.rs`

## Test Data

The tests use realistic data patterns that reflect actual Intel 4004/4001 usage:

- Address ranges: 0x0000 to 0x0FFF (12-bit addressing)
- Data values: 0x00 to 0x0F (4-bit data)
- Timing values: nanosecond precision for hardware simulation
- Pin states: High, Low, and High-Z (tri-state)

## Dependencies

The test suite uses standard Rust testing:

- `std::time`: Timing simulation
- `serde_json`: JSON configuration parsing (for integration tests)
- Standard `#[test]` attributes with `cargo test`

## Continuous Integration

These tests are designed to run in CI environments and provide:

- Deterministic results (no race conditions)
- Reasonable execution time
- Clear failure messages
- Comprehensive coverage of edge cases

## Troubleshooting

If tests fail:

1. Check that timing-related tests account for system timing variations
2. Verify that mock setups match the expected hardware behavior
3. Ensure that property-based tests have appropriate generation strategies
4. Check that integration tests use the correct trait implementations

The test suite is designed to be robust and provide clear feedback about what functionality is broken and why.