Essentials/docs/testing/QuickStart.md

Quick Start Guide: Unit Testing

This guide helps you get started with writing unit tests for PepperDash Essentials components.

Prerequisites

• .NET 8 SDK
• Visual Studio 2022 or VS Code with C# extension

Running Existing Tests

# Navigate to the test project
cd tests/PepperDash.Essentials.Core.Tests

# Run all tests
dotnet test

# Run with coverage
dotnet test --collect:"XPlat Code Coverage"

Creating Your First Test

1. Identify the Component

Choose a component that has business logic you want to test. Look for classes that:

• Have clear inputs and outputs
• Contain conditional logic or algorithms
• Are used by multiple parts of the system

2. Create Test File

Create a new test file in tests/PepperDash.Essentials.Core.Tests/Unit/:

using PepperDash.Essentials.Core.Tests.Abstractions;

namespace PepperDash.Essentials.Core.Tests.Unit
{
    public class YourComponentTests
    {
        [Fact]
        public void YourMethod_WithValidInput_ReturnsExpectedResult()
        {
            // Arrange
            var component = new YourComponent();
            var input = "test data";

            // Act
            var result = component.YourMethod(input);

            // Assert
            Assert.Equal("expected result", result);
        }
    }
}

3. Abstract Dependencies

If your component uses Crestron SDK or other external dependencies:

// Create interface in Abstractions/
public interface IYourDependency
{
    string DoSomething(string input);
}

// Modify your component to use the interface
public class YourComponent
{
    private readonly IYourDependency _dependency;
    
    public YourComponent(IYourDependency dependency)
    {
        _dependency = dependency;
    }
    
    public string YourMethod(string input)
    {
        return _dependency.DoSomething(input);
    }
}

// Test with mocks
[Fact]
public void YourMethod_CallsDependency_ReturnsResult()
{
    // Arrange
    var mockDependency = new Mock<IYourDependency>();
    mockDependency.Setup(x => x.DoSomething("input")).Returns("output");
    var component = new YourComponent(mockDependency.Object);

    // Act
    var result = component.YourMethod("input");

    // Assert
    Assert.Equal("output", result);
    mockDependency.Verify(x => x.DoSomething("input"), Times.Once);
}

Testing Patterns

Testing Exceptions

[Fact]
public void Constructor_WithNullDependency_ThrowsArgumentNullException()
{
    // Act & Assert
    Assert.Throws<ArgumentNullException>(() => new YourComponent(null));
}

Testing Async Methods

[Fact]
public async Task YourAsyncMethod_WithValidInput_ReturnsExpectedResult()
{
    // Arrange
    var component = new YourComponent();

    // Act
    var result = await component.YourAsyncMethod();

    // Assert
    Assert.True(result);
}

Testing Collections

[Fact]
public void GetItems_ReturnsExpectedCount()
{
    // Arrange
    var component = new YourComponent();

    // Act
    var items = component.GetItems();

    // Assert
    Assert.Equal(3, items.Count());
    Assert.Contains(items, x => x.Name == "Expected Item");
}

Common Mistakes to Avoid

1. Testing Implementation Details - Test behavior, not internal implementation
2. Overly Complex Tests - Keep tests simple and focused on one thing
3. Not Testing Edge Cases - Include null values, empty collections, boundary conditions
4. Ignoring Test Performance - Tests should run quickly to enable fast feedback

Debugging Tests

In Visual Studio

• Set breakpoints in test methods
• Use Test Explorer to run individual tests
• Check test output window for detailed information

From Command Line

# Run specific test
dotnet test --filter "YourComponentTests.YourMethod_WithValidInput_ReturnsExpectedResult"

# Run with detailed output
dotnet test --verbosity diagnostic

Next Steps

1. Review Examples - Look at TestableActionSequenceTests.cs for comprehensive examples
2. Start Small - Begin with simple components and build up complexity
3. Read Documentation - Check docs/testing/README.md for detailed patterns
4. Get Feedback - Have your tests reviewed by team members

Need Help?

• Check existing test examples in the codebase
• Review the full testing documentation
• Ask team members for guidance on complex scenarios
• Consider pair programming for your first few tests