MarketAlly.AIPlugin.Extensions/MarketAlly.AIPlugin.Tests/README.md

# MarketAlly.AIPlugin.Tests

## Overview
Comprehensive unit test suite for the MarketAlly.AIPlugin solution, ensuring quality and reliability across core components.

## Test Coverage

### Core Components
- **AIPluginResult**: Result object validation and error handling
- **AgenticEngine**: Core orchestration engine functionality
- **AgenticEngineBuilder**: Builder pattern and configuration
- **ProjectTypeDetector**: Project type detection logic
- **ProjectFileLocator**: File system operations and project discovery

## Test Structure

### Test Categories
1. **Constructor Tests**: Verify proper initialization
2. **Validation Tests**: Input validation and error handling
3. **Behavior Tests**: Core functionality verification
4. **Edge Case Tests**: Boundary conditions and unusual inputs
5. **Integration Points**: Component interaction validation

### Naming Conventions
- Test class: `{ClassName}Tests`
- Test method: `{MethodName}_{Scenario}_{ExpectedBehavior}`
- Example: `Constructor_WithNullInput_ShouldThrowArgumentNullException`

## Running Tests

### Visual Studio
```
Test > Run All Tests
```

### Command Line
```bash
dotnet test
```

### With Coverage
```bash
dotnet test --collect:"XPlat Code Coverage"
```

## Test Frameworks

### Primary
- **xUnit**: Test framework
- **FluentAssertions**: Readable assertions
- **Moq**: Mocking framework

### Packages
```xml
<PackageReference Include="xunit" Version="2.9.2" />
<PackageReference Include="FluentAssertions" Version="6.12.1" />
<PackageReference Include="Moq" Version="4.20.72" />
```

## Test Patterns

### Arrange-Act-Assert (AAA)
```csharp
[Fact]
public void Method_Scenario_ExpectedBehavior()
{
    // Arrange
    var input = "test";
    
    // Act
    var result = Method(input);
    
    // Assert
    result.Should().Be("expected");
}
```

### Theory Tests (Data-Driven)
```csharp
[Theory]
[InlineData("input1", "expected1")]
[InlineData("input2", "expected2")]
public void Method_WithVariousInputs_ProducesCorrectOutput(string input, string expected)
{
    // Arrange & Act
    var result = Method(input);
    
    // Assert
    result.Should().Be(expected);
}
```

### Exception Testing
```csharp
[Fact]
public void Method_WithInvalidInput_ShouldThrow()
{
    // Arrange
    var invalidInput = null;
    
    // Act
    Action act = () => Method(invalidInput);
    
    // Assert
    act.Should().Throw<ArgumentNullException>()
        .WithParameterName("input");
}
```

## Test Guidelines

### DO
- ✅ Test one concept per test method
- ✅ Use descriptive test names
- ✅ Follow AAA pattern consistently
- ✅ Test both success and failure paths
- ✅ Test edge cases and boundaries
- ✅ Use FluentAssertions for readability
- ✅ Mock external dependencies
- ✅ Keep tests fast and isolated

### DON'T
- ❌ Test implementation details
- ❌ Create interdependent tests
- ❌ Use hardcoded paths or dates
- ❌ Test framework code
- ❌ Ignore failing tests
- ❌ Over-mock (test real behavior when possible)

## Coverage Goals

### Target Coverage
- **Line Coverage**: > 80%
- **Branch Coverage**: > 75%
- **Critical Paths**: 100%

### Priority Areas
1. Core business logic
2. Error handling paths
3. Public API surfaces
4. Data validation
5. State management

## Continuous Integration

Tests are automatically run on:
- Pull requests
- Main branch commits
- Release builds

### Build Pipeline
```yaml
- Restore dependencies
- Build solution
- Run all tests
- Generate coverage report
- Publish results
```

## Troubleshooting

### Common Issues

#### Test Discovery Fails
```bash
# Clean and rebuild
dotnet clean
dotnet build
```

#### Tests Timeout
```csharp
// Increase timeout for slow operations
[Fact(Timeout = 5000)] // 5 seconds
```

#### Flaky Tests
- Check for timing dependencies
- Verify test isolation
- Review shared state
- Use deterministic data

## Contributing

### Adding New Tests
1. Follow naming conventions
2. Use appropriate test framework
3. Document complex scenarios
4. Update README if needed
5. Ensure tests pass locally

### Code Review Checklist
- [ ] Tests follow AAA pattern
- [ ] Descriptive test names
- [ ] Edge cases covered
- [ ] No hardcoded values
- [ ] Proper assertions used
- [ ] Tests are isolated
- [ ] Documentation updated

## Resources

### Documentation
- [xUnit Documentation](https://xunit.net/)
- [FluentAssertions](https://fluentassertions.com/)
- [Moq Quickstart](https://github.com/moq/moq4)

### Best Practices
- [Unit Testing Best Practices](https://docs.microsoft.com/en-us/dotnet/core/testing/unit-testing-best-practices)
- [Test-Driven Development](https://martinfowler.com/bliki/TestDrivenDevelopment.html)

## Maintenance

### Regular Tasks
- Review and update test coverage
- Refactor duplicate test code
- Remove obsolete tests
- Update to latest package versions
- Document new testing patterns

### Performance
- Keep test execution time under 5 minutes
- Profile slow tests
- Use parallel execution where safe
- Mock expensive operations

---

**Last Updated**: 2024-12-07
**Maintained By**: QA Team
**Status**: Active Development