What Generics Do for Test Code

A generic type is a class, interface, or method that declares one or more type parameters – placeholders filled in when the type is used. List<T> declares T as its type parameter. List<Order> fills it in with Order. The benefit is that the same list implementation works for every element type, and the compiler enforces that you only ever put Order objects into an Order list.

Test automation infrastructure hits this problem constantly. Consider a TestDataFactory that creates entities for test setup. Without generics, you write a version for each entity type:

// Without generics: three classes, three times the code to maintain
public class UserTestDataFactory
{
    public User Create(Action<User> configure = null)
    {
        var user = new User { CreatedDate = DateTime.UtcNow, IsActive = true };
        configure?.Invoke(user);
        return user;
    }
}

public class OrderTestDataFactory
{
    public Order Create(Action<Order> configure = null)
    {
        var order = new Order { CreatedDate = DateTime.UtcNow, IsActive = true };
        configure?.Invoke(order);
        return order;
    }
}

// ...and again for Product, Category, and every other entity

Every change to the creation pattern – adding a log, changing defaults, adding a CreateMany overload – must be applied to every factory. With generics, you write it once:

// With generics: one class, works for every entity type
public class TestDataFactory<T> where T : class, IEntity, new()
{
    public T Create(Action<T> configure = null)
    {
        var instance = new T();
        instance.CreatedDate = DateTime.UtcNow;
        instance.IsActive    = true;
        configure?.Invoke(instance);
        return instance;
    }

    public IEnumerable<T> CreateMany(int count, Action<T, int> configure = null)
    {
        return Enumerable.Range(1, count).Select(i =>
        {
            var entity = Create();
            configure?.Invoke(entity, i);
            return entity;
        });
    }
}

// One factory works for every entity type
var userFactory    = new TestDataFactory<User>();
var orderFactory   = new TestDataFactory<Order>();
var productFactory = new TestDataFactory<Product>();

var user  = userFactory.Create(u => u.Email = "[email protected]");
var users = userFactory.CreateMany(10, (u, i) => u.Email = $"user{i}@example.com");

The where T : class, IEntity, new() part in the factory above is a constraint – it tells the compiler what T is capable of, and what callers are required to provide. Constraints are the topic of the next chapter, but they're what make the generic body work safely.

Generic Methods in Test Helpers

Type parameters don't have to live on entire classes. A generic method can declare its own type parameter, making just that one operation generic while the containing class stays concrete. This is the right pattern when genericity is scoped to a single utility.

The most immediate example in test automation is JSON deserialization. Without a generic method, every API response requires a separate deserialization call with an explicit type:

// A generic method on a non-generic class
public static class ApiResponseHelper
{
    // T is declared on the method – applies only here, not to the class
    public static T Deserialize<T>(string json)
    {
        return JsonSerializer.Deserialize<T>(json)
            ?? throw new JsonException($"Response could not be parsed as {typeof(T).Name}");
    }
}

// The type argument is explicit – the compiler can't infer it from a string
var order   = ApiResponseHelper.Deserialize<OrderResponse>(responseBody);
var product = ApiResponseHelper.Deserialize<ProductResponse>(catalogJson);

Type Inference Keeps Calls Clean

Type inference lets the compiler deduce the type argument from how a method is called, so callers often don't need to write it explicitly. This is why orders.Where(o => o.IsActive) doesn't need orders.Where<Order>(o => o.IsActive) – the compiler infers T is Order from the sequence type. Well-designed generic methods feel no different to call than non-generic ones.

public static class TestAssertions
{
    // T is inferred from the 'actual' argument – callers don't write it explicitly
    public static void ShouldEqual<T>(T actual, T expected, string message = "")
    {
        if (!EqualityComparer<T>.Default.Equals(actual, expected))
            throw new AssertionException(
                $"{message}\nExpected: {expected}\nActual: {actual}".Trim());
    }
}

// No type argument needed – the compiler infers T from the first argument
TestAssertions.ShouldEqual(response.Status, "Active");     // T = string
TestAssertions.ShouldEqual(response.ItemCount, 3);         // T = int
TestAssertions.ShouldEqual(response.TotalAmount, 49.99m);  // T = decimal

Type inference only works when T appears in at least one parameter type. When T only appears in the return type – as with Deserialize<T>(string json) – the compiler has nothing to infer from, and the type argument must be written explicitly.

A Practical Polling Helper

Generic methods are particularly useful for utility functions that need to work across many scenarios. A typed polling helper is a real example from production test suites – retry an operation until a success condition is met, with the full return type preserved:

// Retry an async operation until a condition is met
public static async Task<T> PollUntilAsync<T>(
    Func<Task<T>> operation,
    Func<T, bool> isSuccess,
    int maxAttempts = 5,
    int delayMs = 500)
{
    for (int attempt = 1; attempt < maxAttempts; attempt++)
    {
        var result = await operation();
        if (isSuccess(result)) return result;
        await Task.Delay(delayMs);
    }

    return await operation(); // Final attempt – let any exception propagate
}

// Wait until the order status changes in the database
var order = await PollUntilAsync(
    () => database.FindOrderAsync(orderId),
    o => o?.Status == "Processing");

// Wait until an email appears in the test inbox
var email = await PollUntilAsync(
    () => testMailbox.FindEmailAsync(subject: "Order Confirmation"),
    e => e != null);

The T on a generic method is scoped entirely to that method – it doesn't interact with any other method in the class. This makes generic methods safe to introduce incrementally: add one wherever a utility needs to work across types without affecting anything else.

Constraints – Making Generics Precise

Without constraints, a type parameter T could be anything – so the compiler only allows operations that every possible type supports, which is essentially just ToString() and Equals(). Type constraints narrow the set of valid types for T, both unlocking operations specific to the constrained category and preventing callers from passing incompatible types.

Constraints are declared with the where keyword after the type parameter list. They serve two purposes: the generic body can call methods specific to the constrained type, and callers that pass the wrong type get a compile error rather than a runtime crash.

The Constraints You'll Use Most

// class: T must be a reference type
// Enables null checks and reference semantics (including the ??= null-coalescing assign)
public class TestCache<T> where T : class
{
    private T _cached;

    public T GetOrCreate(Func<T> factory)
    {
        // '== null' comparison is only legal because of the 'class' constraint
        return _cached ??= factory();
    }
}

// new(): T must have a public parameterless constructor
// Enables 'new T()' inside the generic body
public T CreateInstance<T>() where T : new()
{
    return new T(); // Legal only because of the new() constraint
}

// Interface constraint: T must implement the specified interface
// Unlocks calling that interface's members directly on T
public static void SetAuditFields<T>(T entity) where T : IEntity
{
    // IEntity's members are accessible because of the constraint
    entity.Id          = GenerateTestId();
    entity.CreatedDate = DateTime.UtcNow;
}

Stacking Constraints

Multiple constraints on the same type parameter are combined with commas. Each is independently enforced, and T must satisfy all of them. The class or struct constraint must appear first; interface constraints and new() follow.

// T must be: a reference type, implement IEntity, and have a default constructor
public class TestDataFactory<T> where T : class, IEntity, new()
{
    public T Create(Action<T> configure = null)
    {
        var instance = new T();             // 'new()' enables this
        instance.Id          = NextTestId(); // 'IEntity' enables this
        instance.CreatedDate = DateTime.UtcNow;
        configure?.Invoke(instance);
        return instance;
    }

    public IEnumerable<T> CreateMany(int count, Action<T, int> configure = null)
    {
        return Enumerable.Range(1, count).Select(i =>
        {
            var entity = Create();
            configure?.Invoke(entity, i);
            return entity;
        });
    }

    private static int NextTestId() => Random.Shared.Next(10_000, 99_999);
}

// The interfaces and contract the factory relies on
public interface IEntity
{
    int Id { get; set; }
    DateTime CreatedDate { get; set; }
    bool IsActive { get; set; }
}

// Valid: User implements IEntity and has a default constructor
var factory = new TestDataFactory<User>();
var user    = factory.Create(u => u.Email = "[email protected]");

// Compile error if you try: new TestDataFactory<string>()
// string doesn't implement IEntity – caught before the code runs

Base Class Constraints

When test entities share a common base class rather than an interface, a base class constraint gives the generic body access to those shared members without requiring a separate interface:

// All entities in this project inherit TestEntityBase
public abstract class TestEntityBase
{
    public int Id { get; set; }
    public DateTime CreatedDate { get; set; }
}

// Base class constraint: T must be TestEntityBase or a subclass
public class EntityCleanupTracker<T> where T : TestEntityBase
{
    private readonly List<int> _createdIds = new();

    public T Track(T entity)
    {
        // TestEntityBase.Id is accessible because of the constraint
        _createdIds.Add(entity.Id);
        return entity;
    }

    public async Task CleanupAsync(IDbConnection db)
    {
        foreach (var id in _createdIds)
            await db.ExecuteAsync("DELETE FROM ...", new { Id = id });
    }
}

Well-chosen constraints turn a generic type into a precise contract. Callers who pass a non-compliant type get a compile error naming exactly which constraint wasn't met – rather than a confusing runtime failure several call frames away from the real problem.

Fluent Builders with Generic Base Classes

Test data builders are one of the most valuable patterns in automated testing. A builder provides a fluent API for constructing test entities, using method chaining to configure an object step by step before calling Build(). The challenge is making a reusable base class for builders: if base class methods return BuilderBase, the caller loses access to the concrete builder's methods the moment they call anything shared.

// The problem with a plain base class
public abstract class BuilderBase
{
    // Returns BuilderBase – the concrete subclass methods are lost after this call
    public BuilderBase AsActive()
    {
        // ...
        return this; // Returns BuilderBase, not UserBuilder or OrderBuilder
    }
}

public class UserBuilder : BuilderBase
{
    public UserBuilder WithEmail(string email) { /* ... */ return this; }
}

// Broken chain: after .AsActive(), the compiler only knows about BuilderBase
var user = new UserBuilder()
    .AsActive()           // Returns BuilderBase
    .WithEmail("...");    // Compile error – BuilderBase has no WithEmail

The Self-Referential Pattern

The solution is the self-referential generic pattern: make the base class generic on the type of the concrete subclass. EntityBuilderBase<TEntity, TBuilder> where TBuilder is constrained to be a subclass of the base class itself. Base class methods then return TBuilder instead of the base type, and the compiler knows the concrete type is preserved through the entire chain.

public abstract class EntityBuilderBase<TEntity, TBuilder>
    where TEntity : class, IEntity, new()
    where TBuilder : EntityBuilderBase<TEntity, TBuilder>
{
    // Shared configuration steps are collected as deferred actions
    protected readonly List<Action<TEntity>> Configurations = new();

    // Returns TBuilder – the compiler knows the concrete type is preserved
    public TBuilder AsActive()
    {
        Configurations.Add(e => e.IsActive = true);
        return (TBuilder)this; // Safe: the constraint guarantees 'this' is TBuilder
    }

    public TBuilder WithCreatedDate(DateTime date)
    {
        Configurations.Add(e => e.CreatedDate = date);
        return (TBuilder)this;
    }

    public virtual TEntity Build()
    {
        var entity = new TEntity();
        foreach (var configure in Configurations)
            configure(entity);
        return entity;
    }
}

// Concrete builder: declares itself as TBuilder
public class UserBuilder : EntityBuilderBase<User, UserBuilder>
{
    public UserBuilder WithEmail(string email)
    {
        Configurations.Add(u => u.Email = email);
        return this;
    }

    public UserBuilder WithName(string firstName, string lastName)
    {
        Configurations.Add(u => { u.FirstName = firstName; u.LastName = lastName; });
        return this;
    }
}

public class OrderBuilder : EntityBuilderBase<Order, OrderBuilder>
{
    public OrderBuilder ForUser(int userId)
    {
        Configurations.Add(o => o.UserId = userId);
        return this;
    }

    public OrderBuilder WithTotal(decimal amount)
    {
        Configurations.Add(o => o.TotalAmount = amount);
        return this;
    }
}

// Concrete and base-class methods mix naturally in a single chain
var user = new UserBuilder()
    .WithEmail("[email protected]")  // UserBuilder method – returns UserBuilder
    .WithName("Alex", "Rivera")      // UserBuilder method – returns UserBuilder
    .AsActive()                      // Base class method – still returns UserBuilder
    .WithCreatedDate(DateTime.UtcNow) // Base class method – still returns UserBuilder
    .Build();                         // Returns User

The cast (TBuilder)this inside the base class looks like it might be risky, but the constraint makes it structurally safe: the only way to construct a valid EntityBuilderBase<TEntity, TBuilder> is as a concrete subclass like UserBuilder : EntityBuilderBase<User, UserBuilder>. At runtime, this is always the correct concrete type.

Generic Page Objects in Playwright

Page objects built on a base class face the same problem as builders. If BasePage.WaitForLoadAsync() returns BasePage, any fluent chain through the base class loses access to the concrete page's methods. The self-referential generic pattern solves this in exactly the same way – the base class becomes generic on the type of its own subclass.

// Self-referential base page: TSelf is the concrete page subclass
public abstract class BasePage<TSelf> where TSelf : BasePage<TSelf>
{
    protected IPage Page { get; }

    protected BasePage(IPage page)
    {
        Page = page;
    }

    // Returns TSelf – the concrete page type is preserved through the chain
    public async Task<TSelf> WaitForLoadAsync()
    {
        await Page.WaitForLoadStateAsync(LoadState.NetworkIdle);
        return (TSelf)this;
    }

    public async Task<TSelf> TakeScreenshotAsync(string name)
    {
        await Page.ScreenshotAsync(new() { Path = $"screenshots/{name}.png" });
        return (TSelf)this;
    }
}

// Concrete page: declares itself as TSelf
public class LoginPage : BasePage<LoginPage>
{
    private ILocator UsernameInput => Page.Locator("#username");
    private ILocator PasswordInput => Page.Locator("#password");
    private ILocator LoginButton   => Page.GetByRole(AriaRole.Button, new() { Name = "Sign In" });

    public LoginPage(IPage page) : base(page) { }

    public async Task<LoginPage> EnterUsernameAsync(string username)
    {
        await UsernameInput.FillAsync(username);
        return this;
    }

    public async Task<LoginPage> EnterPasswordAsync(string password)
    {
        await PasswordInput.FillAsync(password);
        return this;
    }

    // Navigation methods that leave the page return the new page type explicitly
    public async Task<DashboardPage> SubmitAsync()
    {
        await LoginButton.ClickAsync();
        return new DashboardPage(Page);
    }
}

// Clean, fluent chain – no casts, every method in the chain is accessible
var dashboard = await new LoginPage(page)
    .WaitForLoadAsync()                      // Returns LoginPage
    .TakeScreenshotAsync("login-before")     // Returns LoginPage
    .EnterUsernameAsync("[email protected]") // Returns LoginPage
    .EnterPasswordAsync("S3cure!")           // Returns LoginPage
    .SubmitAsync();                          // Returns DashboardPage

Notice that SubmitAsync() returns DashboardPage directly, not TSelf. That's intentional: methods that navigate away from the current page return the destination page type explicitly. The self-referential pattern is for methods that stay on the same page and return it for continued chaining.

Generic API Clients and Assertions

API tests have repetitive structure: send a request, check the status code, deserialise the response, null-check the result. Without a generic client, every test repeats this boilerplate around each call. A typed ApiClient centralises the lifecycle once, so test methods focus on the scenario, not the HTTP mechanics.

public class ApiClient
{
    private readonly HttpClient _http;
    private static readonly JsonSerializerOptions _json = new()
    {
        PropertyNameCaseInsensitive = true,
        PropertyNamingPolicy       = JsonNamingPolicy.CamelCase
    };

    public ApiClient(HttpClient http) => _http = http;

    // GET and deserialise to T
    public async Task<T> GetAsync<T>(string endpoint)
    {
        var response = await _http.GetAsync(endpoint);
        response.EnsureSuccessStatusCode();
        return await ReadAs<T>(response);
    }

    // POST with a typed request body, return a typed response
    public async Task<TResponse> PostAsync<TRequest, TResponse>(
        string endpoint, TRequest body)
    {
        var content  = JsonContent.Create(body, options: _json);
        var response = await _http.PostAsync(endpoint, content);
        response.EnsureSuccessStatusCode();
        return await ReadAs<TResponse>(response);
    }

    // Shared null-safe deserialisation
    private async Task<T> ReadAs<T>(HttpResponseMessage response)
    {
        await using var stream = await response.Content.ReadAsStreamAsync();
        return await JsonSerializer.DeserializeAsync<T>(stream, _json)
            ?? throw new InvalidOperationException(
                $"API returned null when {typeof(T).Name} was expected.");
    }
}

// Tests are clean – the HTTP boilerplate is completely out of the way
[Test]
public async Task PlacedOrder_AppearsInUserHistory()
{
    var order = await _api.PostAsync<PlaceOrderRequest, OrderResponse>(
        "/api/orders",
        new PlaceOrderRequest { UserId = _testUserId, Items = _testItems });

    var history = await _api.GetAsync<OrderHistoryResponse>(
        $"/api/users/{_testUserId}/orders");

    Assert.That(history.Orders, Has.Some.Matches<OrderSummary>(
        o => o.OrderId == order.Id));
}

Generic Assertion Extensions

Extension methods on generic types let you write assertion helpers that apply across every collection type with full type safety. These read like requirements and produce specific failure messages that identify exactly what went wrong:

public static class CollectionAssertions
{
    // Asserts exactly one element matches a condition
    public static void ShouldContainSingle<T>(
        this IEnumerable<T> collection,
        Func<T, bool> predicate,
        string because = "")
    {
        var matches = collection.Where(predicate).ToList();
        if (matches.Count == 1) return;

        var description = matches.Count == 0
            ? $"Expected one {typeof(T).Name} matching the condition, but found none."
            : $"Expected one {typeof(T).Name} but found {matches.Count}.";

        throw new AssertionException(string.IsNullOrEmpty(because)
            ? description
            : $"{description} Because: {because}");
    }

    // Asserts two sequences contain the same elements regardless of order
    public static void ShouldBeEquivalentTo<T>(
        this IEnumerable<T> actual,
        IEnumerable<T> expected,
        IEqualityComparer<T>? comparer = null)
    {
        comparer ??= EqualityComparer<T>.Default;
        var actualList   = actual.ToList();
        var expectedList = expected.ToList();

        if (actualList.Count != expectedList.Count ||
            !expectedList.All(e => actualList.Contains(e, comparer)))
        {
            throw new AssertionException(
                $"Collections are not equivalent.\n" +
                $"Expected: [{string.Join(", ", expectedList)}]\n" +
                $"Actual:   [{string.Join(", ", actualList)}]");
        }
    }
}

// Usage: reads like a requirement, fails with a specific message
orders.ShouldContainSingle(
    o => o.UserId == userId && o.Status == "Completed",
    because: "the checkout flow should produce exactly one completed order");

actualProductIds.ShouldBeEquivalentTo(expectedProductIds);

These four patterns – factory, builder, API client, and assertion helpers – are the ones you'll reach for most when building test automation infrastructure. Written once with generics, they serve every entity type in the system, and any improvement to the shared base immediately benefits all consumers.