DEV Community: Mutombo jean-vincent

Two Patterns That Turn Painful Test Setup Into One Readable Line

Mutombo jean-vincent — Sat, 18 Jul 2026 13:28:34 +0000

The Problem

Every test starts with a chore nobody actually asked for. Before you can check a single thing, you have to build the objects the test runs on. And on a domain with any real depth, that's where the time goes.

The backend I work on powers a media platform for music promotion: videos, articles, lyrics, short clips, customers, orders, all the usual moving parts. None of these entities are simple bags of setters. They protect themselves with private constructors, static creation methods, and lifecycles you have to walk through in order: Great for production. Rough on tests.

Here's what it takes to build one published video by hand, with data that looks real. It's the wrong way. Notice how much of it there is:

/// <summary>
/// Stands up a single published video entirely by hand, with no test helpers.
/// </summary>
[Fact]
public async Task SomeTest()
{
    // Arrange
    var faker = new Faker();

    var services = new ServiceCollection();
    services.AddLogging();
    services.AddLocalization();
    services.AddScoped<VideoErrorMessage>();
    ServiceProvider provider = services.BuildServiceProvider();
    VideoErrors errors = new(provider.GetRequiredService<VideoErrorMessage>());

    VideoEntity video = VideoEntity.CreateFree(
        id: Guid.NewGuid(),
        categoryId: categoryId,
        title: faker.Lorem.Sentence(wordCount: 4),
        slug: faker.Lorem.Slug(),
        authorId: Guid.NewGuid(),
        description: faker.Lorem.Paragraph(),
        errors: errors
    );

    video.ScheduleShoot(faker.Date.FutureOffset());
    video.AttachYoutubeVideoUrl(faker.Internet.Url(), errors);
    video.SetThumbnailFileId(Guid.NewGuid());
    video.MarkPendingReview();
    video.Approve();
    video.Publish(errors);

    // ...and only now can the real test begin
}

Count that up. Over twenty lines, and not one of them is what the test is about. Just to get a single argument, you spin up a dependency injection container so it can hand you a localized errors object. Then, because the entity starts life as a draft, getting it to Published means stepping through the lifecycle one legal move at a time, and the YouTube URL has to be on it before you call publish or the whole thing throws. Skip a step, swap two, and you end up with a video in a state no real user could ever create. All of that, for an object you were planning to treat as a given.

Now picture it across thousands of tests, each one wanting a slightly different shape: a paid video, a rejected one, a draft with no URL, ten at once, a request body that actually passes its validator. Copy that setup into every test and three things go wrong:

They get unreadable. The two lines that matter drown in setup noise.
They get fragile. Add one required field and you're touching hundreds of files.
They start lying. Somebody copies a slightly wrong setup and the test passes for the wrong reason.

Building test data is its own problem. It has nothing to do with what any given test is checking, and it deserves its own solution.

The Idea

Two small patterns fix this, and they're better together than apart.

A builder gives you a fluent way to put one object together. It knows the annoying multi step dance (create the draft, attach the URL, push it through review and approval to published) and tucks it behind a few chained methods. You spell out only the bits your test cares about, and it fills in sane, valid defaults for everything else.

A factory gives you names for the setups you reach for over and over. Instead of chaining the same three builder calls in fifty places, you ask for the thing by name. CreatePublished(). CreateRejected(). CreatePaid(customerId, orderItemId). The method name is the intent.

Think of the builder as the engine and the factory as the menu bolted on top. This started as one of each and grew into roughly a hundred builders and thirty factories across the content, core, and identity modules. They all share the same shape, so once you've read one you can pretty much read the rest.

The Entity Builder

Here's the video builder, trimmed to what matters. Watch it eat the entire wall of code from the problem above:

/// <summary>
/// Fluent builder for creating <see cref="VideoEntity"/> instances in tests.
/// For test code, prefer using VideoFactory instead of direct Builder usage.
/// </summary>
internal class VideoBuilder
{
    private readonly Faker _faker = new();

    private Guid _id = Guid.NewGuid();
    private Guid _categoryId;
    private string _title;
    private string _slug;
    private Guid _authorId = Guid.NewGuid();
    private string _description;
    private Guid? _customerId;
    private Guid? _orderItemId;
    private string? _youtubeVideoUrl;
    private string? _rejectionReason;
    private EnumContentStatus _targetStatus = EnumContentStatus.Draft;

    /// <summary>
    /// Initializes the builder for the given category and seeds Faker generated defaults.
    /// </summary>
    /// <param name="categoryId">The category the video belongs to.</param>
    public VideoBuilder(Guid categoryId)
    {
        _categoryId = categoryId;

        // Bogus for readable content; a guid suffix on the unique columns to guarantee no collision
        _title = $"{_faker.Lorem.Sentence(wordCount: 4)} {Guid.NewGuid():N}";
        _slug = $"{_faker.Lorem.Slug()}-{Guid.NewGuid():N}";
        _description = _faker.Lorem.Paragraph();
    }

    /// <summary>
    /// Makes the video a paid video linked to a customer and an order item.
    /// </summary>
    /// <param name="customerId">The commissioning customer.</param>
    /// <param name="orderItemId">The order item the video fulfils.</param>
    /// <returns>The builder instance for chaining.</returns>
    public VideoBuilder WithCustomer(Guid customerId, Guid orderItemId)
    {
        _customerId = customerId;
        _orderItemId = orderItemId;
        return this;
    }

    /// <summary>
    /// Transitions the built video to Approved status.
    /// </summary>
    /// <returns>The builder instance for chaining.</returns>
    public VideoBuilder AsApproved()
    {
        _targetStatus = EnumContentStatus.Approved;
        return this;
    }

    /// <summary>
    /// Transitions the built video to Published status, attaching a valid YouTube URL when none is set.
    /// </summary>
    /// <returns>The builder instance for chaining.</returns>
    public VideoBuilder AsPublished()
    {
        _targetStatus = EnumContentStatus.Published;
        _youtubeVideoUrl ??= TestConstants.Content.Editorial.Video.ValidYoutubeVideoUrl;
        return this;
    }

    /// <summary>
    /// Transitions the built video to Rejected status with a reason.
    /// </summary>
    /// <param name="reason">The rejection reason, or null to use a valid default.</param>
    /// <returns>The builder instance for chaining.</returns>
    public VideoBuilder AsRejected(string? reason = null)
    {
        _targetStatus = EnumContentStatus.Rejected;
        _rejectionReason = reason ?? TestConstants.Content.Editorial.Video.ValidRejectionReason;
        return this;
    }

    /// <summary>
    /// Builds the configured <see cref="VideoEntity"/>, resolving the URL and lifecycle steps.
    /// </summary>
    /// <returns>The constructed video entity.</returns>
    public VideoEntity Build()
    {
        VideoErrors errors = TestErrorsFactory.CreateVideoErrors();

        VideoEntity entity = _customerId.HasValue
            ? VideoEntity.CreatePaid(
                id: _id,
                customerId: _customerId.Value,
                orderItemId: _orderItemId!.Value,
                categoryId: _categoryId,
                title: _title,
                slug: _slug,
                authorId: _authorId,
                description: _description,
                errors: errors
            )
            : VideoEntity.CreateFree(
                id: _id,
                categoryId: _categoryId,
                title: _title,
                slug: _slug,
                authorId: _authorId,
                description: _description,
                errors: errors
            );

        if (_youtubeVideoUrl is not null)
        {
            entity.AttachYoutubeVideoUrl(_youtubeVideoUrl, errors);
        }

        ApplyStatusTransition(entity, errors);
        return entity;
    }

    /// <summary>
    /// Walks the entity from Draft to the requested target status one legal step at a time.
    /// </summary>
    /// <param name="entity">The entity to transition.</param>
    /// <param name="errors">The domain errors facade.</param>
    private void ApplyStatusTransition(VideoEntity entity, VideoErrors errors)
    {
        switch (_targetStatus)
        {
            case EnumContentStatus.PendingReview:
                entity.MarkPendingReview();
                break;
            case EnumContentStatus.Approved:
                entity.MarkPendingReview();
                entity.Approve();
                break;
            case EnumContentStatus.Published:
                entity.MarkPendingReview();
                entity.Approve();
                entity.Publish(errors);
                break;
            case EnumContentStatus.Rejected:
                entity.MarkPendingReview();
                entity.Reject(_rejectionReason!);
                break;
        }
    }
}

A few things worth pointing out.

Every field starts from a valid default: a fresh id, a Faker title and slug, a random author, a Faker paragraph for the description. Call new VideoBuilder(categoryId).Build() and you get a free video in Draft that clears every invariant. You override only what your test cares about, nothing more.

The title and slug are the interesting pair. Both columns are unique in the database, and Faker on its own won't save you there: its word list is finite, so two Lorem.Slug() calls can eventually land on the same value and the second insert blows up. So the builder uses both. Faker gives you something readable, and the guid on the end makes it genuinely unique. The description has no such constraint, so it stays a plain Faker paragraph.

ApplyStatusTransition is the part I like most. Remember typing MarkPendingReview, Approve, Publish by hand back in the problem? It lives here now, once, in the right order, behind a single AsPublished(). All the lifecycle knowledge that used to get copied into every test sits in one switch.

AsPublished() also quietly enforces a domain rule: you can't publish a video without a YouTube URL. So if the test didn't set one, the method drops a valid one in. It's doing what a careful person would do by hand, so nobody has to remember to.

The Entity Factory

The factory is just a flat list of static methods, each naming a scenario and handing off to the builder:

/// <summary>
/// Factory for quickly creating <see cref="VideoEntity"/> instances in tests.
/// </summary>
public static class VideoFactory
{
    /// <summary>
    /// Creates a free video in Draft status.
    /// </summary>
    public static VideoEntity Create(Guid categoryId) => new VideoBuilder(categoryId).Build();

    /// <summary>
    /// Creates a published free video (a YouTube URL is attached for you).
    /// </summary>
    public static VideoEntity CreatePublished(Guid categoryId) => new VideoBuilder(categoryId).AsPublished().Build();

    /// <summary>
    /// Creates an approved free video.
    /// </summary>
    public static VideoEntity CreateApproved(Guid categoryId) => new VideoBuilder(categoryId).AsApproved().Build();

    /// <summary>
    /// Creates a rejected free video.
    /// </summary>
    public static VideoEntity CreateRejected(Guid categoryId) => new VideoBuilder(categoryId).AsRejected().Build();

    /// <summary>
    /// Creates a paid video tied to a customer and an order item.
    /// </summary>
    public static VideoEntity CreatePaid(Guid categoryId, Guid customerId, Guid orderItemId) =>
        new VideoBuilder(categoryId).WithCustomer(customerId, orderItemId).Build();

    /// <summary>
    /// Creates a list of published videos.
    /// </summary>
    public static List<VideoEntity> CreateManyPublished(Guid categoryId, int count) =>
        Enumerable.Range(0, count).Select(_ => CreatePublished(categoryId)).ToList();
}

Every method is a single line, and every one reads like a sentence. CreatePublished says "a published free video" in its name and in its body. CreateManyPublished hands you a whole page of distinct, valid videos with no loop in the test. And notice the factory never repeats any construction logic. It names a combination and lets the builder do the actual work.

Why the Builder Is Hidden and the Factory Is Public

Look at the two declarations again. The builder is internal. The factory is public. That's on purpose, and it holds across the whole suite: all nineteen entity builders are internal, and every factory that wraps them is public.

It comes down to what a test should be allowed to say. An entity in a test should always be a state the real system could actually produce. If any test could grab the builder directly, sooner or later somebody assembles a half valid object to force a stubborn test green, and now that object has drifted away from anything production would ever create. Keeping the builder behind the factory means tests can only ask for named, approved setups. Need one the factory doesn't have yet? Add a method to the factory, out in the open, where the rest of the team can find it and reuse it.

So the rule is easy to remember: in a test you call the factory. The builder is there to keep the factory clean, not to be used on its own.

The Factories Underneath the Builders

There's one more layer, and it clears up something the very first example left hanging. Go back to the builder and look at this line:

VideoErrors errors = TestErrorsFactory.CreateVideoErrors();

Remember that dependency injection container you had to stand up by hand just to get an errors object? It didn't disappear. It moved down here, into a factory every builder shares, written once. The builder never constructs that facade itself. It calls another factory:

/// <summary>
/// Builds real *Errors instances backed by embedded .resx resources for use in test builders.
/// </summary>
public static class TestErrorsFactory
{
    /// <summary>
    /// Creates a real <see cref="VideoErrors"/> facade for the video entity builder.
    /// </summary>
    /// <returns>A configured video errors instance.</returns>
    public static VideoErrors CreateVideoErrors() =>
        new(LocalizerFactory.CreateMessage<VideoErrorMessage>());

    // one method per domain: CreateShortVideoErrors, CreateTagErrors, and so on
}

TestErrorsFactory builds dependencies, not entities, and it sits on top of LocalizerFactory. That localizer factory is exactly where the ServiceCollection, AddLocalization, resolve dance from the opening example ended up, written down one time so no test ever types it again. The layers stack: a test calls an entity factory, the factory drives a builder, the builder asks the errors factory for a real errors object, and that asks the localizer factory for real messages. Each layer hides one flavor of ugliness so the one above it stays short.

Two more helpers turn up everywhere. TestConstants holds the known good literals, the titles, slugs, and descriptions builders start from. And Bogus (that Faker field) covers the cases where variety or uniqueness matters more than a fixed value. Constants for what should be predictable, Faker for what should vary, and either way the builder starts from something valid.

What the Tests Look Like Now

Go back to that twenty line arrange block from the start. With the factory it shrinks to this:

VideoEntity published = VideoFactory.CreatePublished(category.Id);
VideoEntity rejected = VideoFactory.CreateRejected(category.Id);

The setup finally says what it means. One published, one rejected. No container, no errors object, no slug wrangling, no lifecycle steps.

But two lines out of context don't prove much, so here's a real one, top to bottom. It rates a published video and checks the rating actually landed in the database. The part to watch is the arrange:

/// <summary>
/// Integration tests for the PublicRateVideo endpoint. The base class supplies
/// <c>Client</c> (an HttpClient to the test server), SeedAsync, and CreateDbContext.
/// </summary>
public class PublicRateVideoEndpointV1Tests(PostgresFixture db) : BaseApiTest(db)
{
    /// <summary>
    /// Seeds a published video with its category and content type, and returns it.
    /// </summary>
    private async Task<VideoEntity> SeedPublishedVideoAsync()
    {
        return await SeedAsync<ContentDbContext, VideoEntity>(ctx =>
        {
            ContentTypeEntity contentType = ContentTypeFactory.Create();
            CategoryEntity category = CategoryFactory.Create(contentType.Id);
            VideoEntity video = VideoFactory.CreatePublished(category.Id);

            ctx.ContentTypes.Add(contentType);
            ctx.Categories.Add(category);
            ctx.Videos.Add(video);

            return video;
        });
    }

    /// <summary>
    /// A visitor rating a published video stores the rating against that user.
    /// </summary>
    [Fact]
    public async Task RateVideo_AsVisitor_WithValidData_StoresRating()
    {
        // Arrange
        Client.AuthenticateAsVisitor();
        VideoEntity video = await SeedPublishedVideoAsync();
        PublicRateVideoRequest request = new PublicRateVideoRequestBuilder().Build();

        // Act
        var response = await Client.PostAsJsonAsync(Routes.Public.Videos.Ratings(video.Id), request);

        // Assert
        response.StatusCode.Should().Be(HttpStatusCode.OK);

        await using ContentDbContext verifyDb = CreateDbContext<ContentDbContext>();
        VideoRatingEntity? rating = await verifyDb.VideoRatings.FirstOrDefaultAsync(r =>
            r.VideoId == video.Id && r.UserId == TestUser.VisitorId
        );
        rating.Should().NotBeNull();
        rating!.Stars.Should().Be(request.Stars);
    }
}

Look at what the arrange is doing. A video can't exist without a category, and a category can't exist without a content type, so there's a three step chain in SeedPublishedVideoAsync, and it's three factory calls. The request is a single builder call. Everything after // Act is the actual test. If the video model grows a new required field tomorrow, not one line of this test moves, because all of that lives inside VideoFactory and VideoBuilder.

And it's the same story across modules. A file over in core and a user over in identity expose the same builder plus factory shape, so pulling a thumbnail file or an author into a test reads like a story about how things connect instead of a pile of setup.

Keeping the Defaults Honest

There's one rule this whole thing lives or dies by: the default a builder produces has to be valid.

If new VideoBuilder(categoryId).Build() handed back something the domain rejected, every test would have to patch it up first, and you'd be right back where you started. So the defaults are picked to clear every invariant: a real title, a unique slug, a believable description, Draft status as the plainest legal starting point. The builder gives you the most boring legal version of the thing, and each With and As nudges it toward one specific case.

It's also why the builders go through the real creation methods and lifecycle calls instead of reflection or some bypassed constructor. Forcing fields into place and skipping the invariants would be easy, and it would let tests build objects production never could. Then the tests slowly stop matching reality. By going through CreateFree, CreatePaid, and the actual MarkPendingReview, Approve, and Publish calls, whatever the builder returns is a state the real system can genuinely reach.

What I Got Out of It

Once this was the standard across the codebase, a few things got noticeably better.

Arrange blocks became about intent. Setup names the scenario and stops. You read "published plus rejected" or "a draft" instead of a recipe.
Domain changes stopped wrecking the suite. When the entity picked up a new field, the builder was the one place to look. No test mentioned the field, so no test had to change.
Uniqueness stopped biting. Constraint violations don't surprise me anymore, because the builders mint unique titles and slugs on their own.
Edge cases got names. CreatePublished, CreateRejected, CreatePaid turned vague setup into stated intent. A new teammate can guess each one without opening the builder.
Validation tests are one liners. A public request builder and one overridden field is enough to prove an endpoint rejects bad input.
Learn one, read them all. A hundred builders and thirty factories sounds like a lot, but it's the same handful of shapes over and over. Read VideoFactory once and you can read every factory in the project on sight.

The price is real but small. Every entity and request gets a little builder, entities get a factory too, and you have to keep the defaults valid as the model changes. But these files are short, they barely move, and they put all the construction knowledge in one place. I'll take a tidy builder and a one line factory over a twenty line arrange block copy pasted across a hundred tests, every time.

Offline First: Using the Decorator Pattern to Cache API Responses in Flutter

Mutombo jean-vincent — Mon, 08 Jun 2026 10:23:53 +0000

The Problem

Imagine the network disappears mid-session. What does your app show? For a long time, mine showed nothing. The platform serves articles, videos, user profiles, and settings, all pulled from a .NET backend. No connection meant no data, and I had not planned for that at all.

The first version was simple. A screen called a use case, the use case called a repository, the repository called the API. If the API responded, great. If not, the user saw an error. That is fine for a first pass, but it is not acceptable for a real app. Users expect data to be there, especially for things they have already seen.

The obvious answer is caching. Fetch from the API, store the result locally, and the next time the user opens the app, show the cached data immediately while the fresh data loads in the background. But how you wire that up matters a lot. I did not want the caching logic mixed into my use cases or bleeding into the domain layer. I wanted the rest of the app to be completely unaware that caching was happening at all.

That is where the Proxy and Decorator patterns came in.

The Idea

Both patterns involve wrapping an object and adding behavior around it without changing the interface. The difference is mostly about intent:

Proxy controls access to the real object. It can intercept calls to add caching, authorization checks, lazy loading, or logging. The caller does not know whether it is talking to the real thing or the proxy.
Decorator adds new behavior to an existing object while delegating the original behavior to it. You stack decorators on top of each other, each one adding one responsibility.

In practice, the two patterns look almost identical in code. What I ended up with in the mobile app is a Decorator at the repository layer: a class that implements the same repository interface as the remote implementation, wraps it, and adds local storage behavior on top of it without the rest of the app ever knowing.

The architecture looks like this:

Use Case
    ↓
ISettingsRepository (interface)
    ↓
SettingsCachedRepository (decorator, implements ISettingsRepository)
    ↓
SettingsRemoteRepository (real implementation, also implements ISettingsRepository)
    ↓
HTTP API via Chopper/Dio
    ↓
Backend: /api/v1/settings/profile

The use case only knows about ISettingsRepository. The dependency injection container decides which concrete class gets injected. Everything below the interface is invisible to the caller.

The Implementation

The Interface

First, there is a port (interface) that defines what the repository can do. This is the contract that both the remote and the cached implementations must honour:

/// Repository port for settings operations.
///
/// Both the remote and the cached implementations satisfy this contract.
/// Use cases depend only on this interface, never on concrete classes.
abstract class ISettingsRepository {
  Future<Either<Failure, ProfileResponseEntity>> updateProfile(ProfileModel profile);
  Future<Either<Failure, ProfileResponseEntity>> updateAvatar(File avatarFile);
}

Notice the return type: Either<Failure, T>. This is from fpdart, a functional programming library for Dart. Instead of throwing exceptions, every repository method returns a Left(failure) on error or a Right(value) on success. The caller pattern-matches on the result. No try-catch in use cases, no unhandled exceptions flying up the stack.

The Remote Repository

The remote repository is the real implementation. It calls the API through a data source, maps the DTO response into a domain entity, and wraps errors into Left(failure):

/// Remote settings repository.
///
/// Calls the API through the remote data source and maps DTOs to domain entities.
/// All errors are caught and returned as Left(Failure), never thrown.
class SettingsRemoteRepository implements ISettingsRepository {
  final ISettingsRemoteDataSource _remoteDataSource;

  const SettingsRemoteRepository(this._remoteDataSource);

  @override
  Future<Either<Failure, ProfileResponseEntity>> updateProfile(ProfileModel profile) async {
    try {
      final response = await _remoteDataSource.updateProfile(profile);
      final profileEntity = SettingsMapper.profileResponseFromDto(response);
      return Right(profileEntity);
    } on ServerException catch (exception) {
      return Left(ProblemMapper.toFailure(exception));
    }
  }

  @override
  Future<Either<Failure, ProfileResponseEntity>> updateAvatar(File avatarFile) async {
    try {
      final response = await _remoteDataSource.updateAvatar(avatarFile);
      final profileEntity = SettingsMapper.avatarResponseFromDto(response);
      return Right(profileEntity);
    } on ServerException catch (exception) {
      return Left(ProblemMapper.toFailure(exception));
    }
  }

}

This class knows nothing about local storage. Its one job is to make HTTP calls and translate results.

The Cached Repository (The Decorator)

Here is where the pattern pays off. The cached repository also implements ISettingsRepository, but instead of making API calls itself, it delegates to the inner remote repository and then persists the result locally if the call succeeded:

/// Cached settings repository (decorator pattern).
///
/// Wraps the inner repository and adds local caching functionality.
/// Delegates remote operations to the inner repository, then persists
/// successful results to local storage via auth local datasource.
/// The rest of the app never knows this layer exists.
class SettingsCachedRepository implements ISettingsRepository {
  final ISettingsRepository _remoteRepository;
  final IAuthLocalDataSource _localDataSource;

  const SettingsCachedRepository(this._remoteRepository, this._localDataSource);

  @override
  Future<Either<Failure, ProfileResponseEntity>> updateProfile(ProfileModel profile) async {
    final result = await _remoteRepository.updateProfile(profile);

    // Only persist if the remote call succeeded
    return result.fold(
      (failure) => Left(failure),
      (profileResponse) async {
        try {
          await _localDataSource.setUser(UserModel.fromEntity(profileResponse.user));
          return Right(profileResponse);
        } on CacheException catch (exception) {
          return Left(ProblemMapper.toFailure(exception));
        }
      },
    );
  }

  @override
  Future<Either<Failure, ProfileResponseEntity>> updateAvatar(File avatarFile) async {
    final result = await _remoteRepository.updateAvatar(avatarFile);

    // Only persist if the remote call succeeded
    return result.fold(
      (failure) => Left(failure),
      (profileResponse) async {
        try {
          await _localDataSource.setUser(UserModel.fromEntity(profileResponse.user));
          return Right(profileResponse);
        } on CacheException catch (exception) {
          return Left(ProblemMapper.toFailure(exception));
        }
      },
    );
  }

}

A few things worth pointing out:

Only cache on success. The result.fold(...) call handles both branches. If the remote call returned a Left(failure), the decorator passes the failure through unchanged. It never writes stale or partial data to local storage. The cache only ever holds data that the server confirmed was saved successfully.

The decorator does not know about HTTP. It does not import Chopper/Dio or touch any networking code. It only knows about the ISettingsRepository interface and the IAuthLocalDataSource interface. The two responsibilities, talking to the API and talking to local storage, are in separate classes and stay there. This also means swapping the HTTP client is trivial. The project uses Chopper, but Dio, http, or Retrofit would work exactly the same way. The decorator never sees any of it.

Local Storage with Hive

The local data source uses Hive CE, a fast, pure-Dart key-value store. Each module has its own Hive box, its own set of constants, and its own Hive model classes. The auth module's local data source writes and reads UserModel instances from a dedicated auth_box:

// hive.constants.dart
const String kAuthBox = 'auth_box';
const int kUserTypeId = 0;
const String kUserKey = 'user';

/// Hive-backed implementation of IAuthLocalDataSource.
///
/// Reads and writes UserModel to the auth_box using Hive's put/get/delete API.
/// Throws typed CacheException subclasses so errors can be mapped to Failure
/// by the repository layer.
class AuthLocalDataSource implements IAuthLocalDataSource {
  final Box<dynamic> _authBox;

  AuthLocalDataSource(this._authBox);

  @override
  Future<void> setUser(UserModel user) async {
    try {
      await _authBox.put(kUserKey, user);
    } catch (e) {
      throw WriteFailedCacheException(
        instance: 'AuthLocalDataSource.setUser',
        detail: t.auth.cacheError.setUser(error: e.toString()),
      );
    }
  }

  @override
  Future<UserModel?> getUser() async {
    try {
      return _authBox.get(kUserKey) as UserModel?;
    } catch (e) {
      throw ReadFailedCacheException(
        instance: 'AuthLocalDataSource.getUser',
        detail: t.auth.cacheError.getUser(error: e.toString()),
      );
    }
  }

  @override
  Stream<UserModel?> watchUser() async* {
    try {
      // Emit the current value immediately, then stream all future changes
      yield _authBox.get(kUserKey) as UserModel?;

      await for (final event in _authBox.watch(key: kUserKey)) {
        yield event.value as UserModel?;
      }
    } catch (e) {
      throw ReadFailedCacheException(
        instance: 'AuthLocalDataSource.watchUser',
        detail: t.auth.cacheError.watchUser(error: e.toString()),
      );
    }
  }

  @override
  Future<void> clearUser() async {
    try {
      await _authBox.delete(kUserKey);
    } catch (e) {
      throw WriteFailedCacheException(
        instance: 'AuthLocalDataSource.clearUser',
        detail: t.auth.cacheError.clearUser(error: e.toString()),
      );
    }
  }
}

The watchUser() method is particularly useful. It yields the current stored value immediately when a subscriber starts listening, then continues yielding every time the Hive box emits a change event for that key. A BLoC or Provider widget can subscribe to this stream and reactively update the UI whenever the cached user changes, for example right after updateProfile writes new data.

Hive Initialization

Hive needs to be initialized once at app startup, before any box is accessed. Each module registers its own type adapters and opens its own box. For the auth module that looks like this:

/// Initializes Hive and opens all required boxes.
///
/// Called once in main() before runApp().
Future<void> initializeHive() async {
  final directory = await getApplicationDocumentsDirectory();
  Hive.init(directory.path);

  // Generated by hive_ce, registers all @HiveType annotated models
  Hive.registerAdapters();

  await Hive.openBox(kAuthBox);
}

The Hive.registerAdapters() call is code-generated. Every model annotated with @HiveType gets an adapter generated at build time. When a new module needs persistence, you add a new box constant, annotate its model class, run dart run build_runner build, and add the box to initializeHive().

Wiring It Up with Dependency Injection

The final piece is the DI container. This is where the proxy/decorator composition actually happens. The use case gets SettingsCachedRepository injected, which in turn gets SettingsRemoteRepository and AuthLocalDataSource injected:

// In the module's DI registration:
getIt.registerLazySingleton<ISettingsRepository>(
  () => SettingsCachedRepository(
    getIt<SettingsRemoteRepository>(),   // inner: talks to the API
    getIt<IAuthLocalDataSource>(),       // local storage layer
  ),
);

The use case asks for ISettingsRepository. It gets SettingsCachedRepository. That class forwards calls to SettingsRemoteRepository and then persists results through IAuthLocalDataSource. The entire chain is transparent to everything above it.

What I Got Out of It

A few things changed after putting this in place:

Use cases stayed clean. They call the repository interface and handle Either<Failure, T>. They have no idea that caching exists. If I want to add or remove caching from a module, I change one line in the DI registration, nothing else.
Cache writes never corrupt data. Because the decorator only persists on Right(...), the local storage is always consistent with a confirmed server response. A network failure means no write. A partial response means no write. The cache either has the full, validated data, or nothing.
The local data source is independently testable. AuthLocalDataSource takes a Box<dynamic> in its constructor. In tests, you pass a fake or in-memory box. You can verify that setUser writes the right key and that watchUser emits updates without spinning up any networking code.
Reactivity is free. Hive's box.watch(key: ...) stream means that any widget subscribed to watchUser() automatically sees changes the moment the decorator writes new data after a successful profile update. No manual notification, no separate state management event.

The pattern is not free. You end up with one more class per module that needs caching, and you have to be deliberate about which operations get cached and which do not. But that deliberateness is a feature. You are forced to think about what is worth persisting, what the staleness policy is, and what happens when the write fails. Each of those decisions ends up in one place, the cached repository, and nowhere else.

How to use the Specification Pattern to Clean Up Query Logic in C#, .NET

Mutombo jean-vincent — Tue, 26 May 2026 13:29:42 +0000

The Problem

I was building a content management platform with a .NET 9 backend. The platform manages videos, articles, lyrics, and a bunch of lookup tables. Pretty standard stuff. But the repository layer started getting ugly fast.

Every time I needed to query something, I was writing a new method on the repository. Need to find a video by ID? New method. By slug? Another method. By status? Another one. Search by title? You guessed it.

Here is what the video repository was starting to look like:

/// <summary>
/// Retrieves a video by its unique identifier.
/// </summary>
Task<VideoEntity?> GetByIdAsync(Guid id, CancellationToken ct);

/// <summary>
/// Retrieves a video by its URL-safe slug.
/// </summary>
Task<VideoEntity?> GetBySlugAsync(string slug, CancellationToken ct);

/// <summary>
/// Retrieves all videos matching a given content status.
/// </summary>
Task<List<VideoEntity>> GetByStatusAsync(EnumContentStatus status, CancellationToken ct);

/// <summary>
/// Retrieves all videos belonging to a given category.
/// </summary>
Task<List<VideoEntity>> GetByCategoryAsync(Guid categoryId, CancellationToken ct);

/// <summary>
/// Searches videos by title and description.
/// </summary>
Task<List<VideoEntity>> SearchAsync(string search, CancellationToken ct);

/// <summary>
/// Retrieves videos matching both a status and a category.
/// </summary>
Task<List<VideoEntity>> GetByStatusAndCategoryAsync(EnumContentStatus status, Guid categoryId, CancellationToken ct);

/// <summary>
/// Searches videos filtered by a given status.
/// </summary>
Task<List<VideoEntity>> SearchByStatusAsync(string search, EnumContentStatus status, CancellationToken ct);

// ... and it kept growing

The real pain was when I needed to combine filters. The admin panel lets you filter videos by status, by category, and search by text, all at the same time. Every combination of optional filters was becoming its own method, or worse, one giant method full of if statements:

/// <summary>
/// Retrieves a paginated list of videos with optional search, status, and category filters.
/// </summary>
/// <param name="search">Optional search term to filter by title and description.</param>
/// <param name="status">Optional content status filter.</param>
/// <param name="categoryId">Optional category filter.</param>
/// <param name="ct">Token to observe for cancellation requests.</param>
/// <returns>A list of matching video entities.</returns>
public async Task<List<VideoEntity>> GetAllAsync(
    string? search, EnumContentStatus? status, Guid? categoryId, CancellationToken ct)
{
    IQueryable<VideoEntity> query = context.Videos;

    if (!string.IsNullOrWhiteSpace(search))
    {
        string pattern = $"%{search}%";
        query = query.Where(v =>
            EF.Functions.ILike(v.Title, pattern) ||
            (v.Description != null && EF.Functions.ILike(v.Description, pattern)));
    }

    if (status.HasValue)
    {
        query = query.Where(v => v.Status == status.Value);
    }

    if (categoryId.HasValue)
    {
        query = query.Where(v => v.CategoryId == categoryId.Value);
    }

    return await query.ToListAsync(ct);
}

This works, but the filtering logic is buried inside the repository. You cannot reuse any of it. If the lyrics module needs the same search pattern, you copy paste the code. If you want to test whether a video matches certain criteria without hitting the database, you are stuck. And every time a new filter comes in, you are back in this method adding another if block.

I had the same problem across videos, articles, lyrics, tags, categories, pricing tiers, promotion levels, customers. Every module had its own version of this mess.

The Idea

I had read about the Specification pattern before but never actually used it in a real project. The idea is simple: take each filtering condition and turn it into its own class. Each class holds one rule, expressed as a Func<T, bool> (or more precisely, an Expression<Func<T, bool>> so Entity Framework can translate it to SQL). Then you compose these small classes together using And, Or, and Not.

Instead of the repository knowing about every possible filter combination, it just takes a specification and applies it. The caller decides what filters to use.

The Implementation

First, I defined a simple interface that every specification must implement:

/// <summary>
/// Represents a specification pattern that defines filtering criteria for objects of type T.
/// </summary>
/// <typeparam name="T">The type of object the specification applies to.</typeparam>
public interface ISpecification<T>
{
    /// <summary>
    /// Converts the specification into a LINQ expression.
    /// </summary>
    /// <returns>An expression that represents the filtering criteria.</returns>
    Expression<Func<T, bool>> ToExpression();

    /// <summary>
    /// Evaluates whether a given object satisfies the specification.
    /// </summary>
    /// <param name="entity">The object to evaluate.</param>
    /// <returns>True if the object satisfies the specification, otherwise false.</returns>
    bool IsSatisfiedBy(T entity);
}

Then I built the base class on top of it:

/// <summary>
/// Base class for defining specifications and composing them using logical operators.
/// </summary>
/// <typeparam name="T">The type the specification applies to.</typeparam>
public abstract class Specification<T> : ISpecification<T>
{
    /// <summary>
    /// Converts the specification into a LINQ expression tree.
    /// </summary>
    public abstract Expression<Func<T, bool>> ToExpression();

    /// <summary>
    /// Evaluates whether a given entity satisfies this specification in memory.
    /// </summary>
    /// <param name="entity">The entity to evaluate.</param>
    /// <returns>True if the entity matches the specification.</returns>
    public bool IsSatisfiedBy(T entity)
    {
        Func<T, bool> predicate = ToExpression().Compile();
        return predicate(entity);
    }

    /// <summary>
    /// Combines the current specification with another using logical AND.
    /// </summary>
    public Specification<T> And(Specification<T> other)
        => new AndSpecification<T>(this, other);

    /// <summary>
    /// Combines the current specification with another using logical OR.
    /// </summary>
    public Specification<T> Or(Specification<T> other)
        => new OrSpecification<T>(this, other);

    /// <summary>
    /// Inverts the current specification using logical NOT.
    /// </summary>
    public Specification<T> Not()
        => new NotSpecification<T>(this);
}

Two things to note here. The ToExpression() method returns an Expression tree, not a compiled delegate. This is important because EF Core needs the expression tree to translate it into SQL. If you just use Func<T, bool>, EF will pull every row from the database and filter in memory. Bad.

The IsSatisfiedBy method compiles the expression and runs it in memory. I use this in unit tests to verify that a specification matches or rejects a given entity without needing a database at all.

The And, Or, and Not methods return composite specifications that combine expression trees at the LINQ level. Here is how they work:

/// <summary>
/// Combines two specifications using logical AND.
/// </summary>
public class AndSpecification<T>(Specification<T> left, Specification<T> right) : Specification<T>
{
    /// <summary>
    /// Combines two specification expressions using logical AND.
    /// </summary>
    /// <returns>An expression that evaluates to true when both specifications are satisfied.</returns>
    public override Expression<Func<T, bool>> ToExpression()
    {
        Expression<Func<T, bool>> leftExpr = left.ToExpression();
        Expression<Func<T, bool>> rightExpr = right.ToExpression();

        ParameterExpression param = Expression.Parameter(typeof(T));
        BinaryExpression body = Expression.AndAlso(
            Expression.Invoke(leftExpr, param),
            Expression.Invoke(rightExpr, param)
        );

        return Expression.Lambda<Func<T, bool>>(body, param);
    }
}

/// <summary>
/// Combines two specifications using logical OR.
/// </summary>
public class OrSpecification<T>(Specification<T> left, Specification<T> right) : Specification<T>
{
    /// <summary>
    /// Combines two specification expressions using logical OR.
    /// </summary>
    /// <returns>An expression that evaluates to true when either specification is satisfied.</returns>
    public override Expression<Func<T, bool>> ToExpression()
    {
        Expression<Func<T, bool>> leftExpr = left.ToExpression();
        Expression<Func<T, bool>> rightExpr = right.ToExpression();

        ParameterExpression param = Expression.Parameter(typeof(T));
        BinaryExpression body = Expression.OrElse(
            Expression.Invoke(leftExpr, param),
            Expression.Invoke(rightExpr, param)
        );

        return Expression.Lambda<Func<T, bool>>(body, param);
    }
}

/// <summary>
/// Inverts a specification using the logical NOT.
/// </summary>
public class NotSpecification<T> : Specification<T>
{
    private readonly Specification<T> _inner;

    /// <summary>
    /// Initializes a new instance of the NotSpecification class.
    /// </summary>
    /// <param name="inner">The specification to negate.</param>
    public NotSpecification(Specification<T> inner)
    {
        _inner = inner;
    }

    /// <summary>
    /// Inverts the inner specification expression using logical NOT.
    /// </summary>
    /// <returns>An expression that evaluates to true when the inner specification is not satisfied.</returns>
    public override Expression<Func<T, bool>> ToExpression()
    {
        Expression<Func<T, bool>> innerExpr = _inner.ToExpression();
        ParameterExpression param = Expression.Parameter(typeof(T));
        UnaryExpression body = Expression.Not(Expression.Invoke(innerExpr, param));

        return Expression.Lambda<Func<T, bool>>(body, param);
    }
}

These three classes are the glue. They take expression trees and stitch them together using Expression.AndAlso, Expression.OrElse, and Expression.Not. EF Core sees the final composed expression and translates the whole thing to SQL. No in-memory evaluation.

With those in place, I created concrete specifications for each filter. For videos:

/// <summary>
/// Specification that matches a video by its unique identifier.
/// </summary>
public class VideoByIdSpecification(Guid id) : Specification<VideoEntity>
{
    /// <inheritdoc />
    public override Expression<Func<VideoEntity, bool>> ToExpression()
    {
        return video => video.Id == id;
    }
}

/// <summary>
/// Specification that matches videos by their content status.
/// </summary>
public class VideoByStatusSpecification(EnumContentStatus status) : Specification<VideoEntity>
{
    /// <inheritdoc />
    public override Expression<Func<VideoEntity, bool>> ToExpression()
    {
        return video => video.Status == status;
    }
}

/// <summary>
/// Specification for full-text search across video Title, Description,
/// MetaTitle, and MetaDescription fields.
/// Uses case-insensitive matching (ILIKE in PostgreSQL).
/// </summary>
public class VideoSearchSpecification(string search) : Specification<VideoEntity>
{
    /// <inheritdoc />
    public override Expression<Func<VideoEntity, bool>> ToExpression()
    {
        string pattern = $"%{search}%";
        return video =>
            EF.Functions.ILike(video.Title, pattern)
            || (video.Description != null && EF.Functions.ILike(video.Description, pattern))
            || (video.MetaTitle != null && EF.Functions.ILike(video.MetaTitle, pattern))
            || (video.MetaDescription != null && EF.Functions.ILike(video.MetaDescription, pattern));
    }
}

Each one is tiny. Each one does exactly one thing. And they are all testable on their own.

To apply them to EF Core queries, I wrote an extension method:

/// <summary>
/// Applies a specification to an IQueryable, converting it to a Where clause.
/// Bridges the Specification pattern with EF Core queries.
/// </summary>
/// <typeparam name="T">The entity type.</typeparam>
/// <param name="query">The queryable to apply the specification to.</param>
/// <param name="specification">The specification containing the filtering logic.</param>
/// <returns>A filtered queryable based on the specification criteria.</returns>
public static IQueryable<T> ApplySpecification<T>(
    this IQueryable<T> query, ISpecification<T> specification)
{
    return query.Where(specification.ToExpression());
}

One line. The specification turns into a .Where() clause. EF Core translates the expression tree into a SQL WHERE clause. No in-memory filtering.

Composing Filters with a Builder

The specifications handle individual rules, but I still needed a clean way to combine optional filters. I did not want the repository method to go back to a chain of if statements. So I defined a builder interface per module:

/// <summary>
/// Interface for building dynamic video queries using specifications.
/// Implements the Builder pattern to construct complex queries without conditional logic.
/// </summary>
public interface IVideoQueryBuilder
{
    /// <summary>
    /// Adds a full-text search filter across Title, Description, MetaTitle, and MetaDescription.
    /// </summary>
    IVideoQueryBuilder WithSearch(string? search);

    /// <summary>
    /// Adds a content status filter to the query.
    /// </summary>
    IVideoQueryBuilder WithStatus(EnumContentStatus? status);

    /// <summary>
    /// Adds a category filter to the query.
    /// </summary>
    IVideoQueryBuilder WithCategory(Guid? categoryId);

    /// <summary>
    /// Builds and returns the final specification.
    /// Returns null if no filters were applied.
    /// </summary>
    Specification<VideoEntity>? Build();
}

Then the implementation:

/// <summary>
/// Builder for constructing dynamic video queries using specifications.
/// Implements the Builder pattern to eliminate conditional logic in query construction.
/// </summary>
public class VideoQueryBuilder : IVideoQueryBuilder
{
    private Specification<VideoEntity>? _specification;

    /// <summary>
    /// Adds a full-text search filter if the search term is not empty.
    /// </summary>
    /// <param name="search">Optional search term.</param>
    public IVideoQueryBuilder WithSearch(string? search)
    {
        if (string.IsNullOrWhiteSpace(search)) return this;

        var searchSpec = new VideoSearchSpecification(search);
        CombineSpecification(searchSpec);
        return this;
    }

    /// <summary>
    /// Adds a content status filter if a status is provided.
    /// </summary>
    /// <param name="status">Optional content status.</param>
    public IVideoQueryBuilder WithStatus(EnumContentStatus? status)
    {
        if (!status.HasValue) return this;

        var statusSpec = new VideoByStatusSpecification(status.Value);
        CombineSpecification(statusSpec);
        return this;
    }

    /// <summary>
    /// Adds a category filter if a category ID is provided.
    /// </summary>
    /// <param name="categoryId">Optional category identifier.</param>
    public IVideoQueryBuilder WithCategory(Guid? categoryId)
    {
        if (!categoryId.HasValue) return this;

        var categorySpec = new VideoByCategorySpecification(categoryId.Value);
        CombineSpecification(categorySpec);
        return this;
    }

    /// <summary>
    /// Builds the final composed specification, or null if no filters were added.
    /// </summary>
    public Specification<VideoEntity>? Build()
    {
        return _specification;
    }

    /// <summary>
    /// Combines a new specification with the existing one using logical AND.
    /// </summary>
    private void CombineSpecification(Specification<VideoEntity> spec)
    {
        _specification = _specification is null ? spec : _specification.And(spec);
    }
}

The builder chains optional filters. If a parameter is null or empty, it skips that filter. If multiple filters are provided, it combines them with And. The repository just calls Build() and applies the result:

/// <summary>
/// Retrieves a paginated list of videos using the specification builder.
/// </summary>
/// <param name="page">The 1-based page number.</param>
/// <param name="pageSize">The number of items per page.</param>
/// <param name="search">Optional search term.</param>
/// <param name="status">Optional content status filter.</param>
/// <param name="categoryId">Optional category filter.</param>
/// <param name="ct">Token to observe for cancellation requests.</param>
/// <returns>A tuple containing the list of videos and the total count.</returns>
public async Task<(List<VideoEntity>, int)> GetAllAsync(
    int page, int pageSize, string? search,
    EnumContentStatus? status, Guid? categoryId,
    CancellationToken ct)
{
    IQueryable<VideoEntity> query = context.Videos;

    Specification<VideoEntity>? spec = new VideoQueryBuilder()
        .WithSearch(search)
        .WithStatus(status)
        .WithCategory(categoryId)
        .Build();

    if (spec is not null)
    {
        query = query.ApplySpecification(spec);
    }

    int totalCount = await query.CountAsync(ct);
    List<VideoEntity> videos = await query
        .Skip((page - 1) * pageSize)
        .Take(pageSize)
        .ToListAsync(ct);

    return (videos, totalCount);
}

No if chains in the repository. No conditional logic at all. The builder handles all of that.

Testing

This is where the pattern really paid off. Testing a specification does not require a database. You just create an entity in memory and call IsSatisfiedBy:

/// <summary>
/// Verifies that a video in Draft status satisfies the Draft specification.
/// </summary>
[Fact]
public void VideoByStatusSpecification_WithMatchingStatus_ShouldReturnTrue()
{
    // Arrange
    VideoEntity video = VideoFactory.Create(categoryId);
    var spec = new VideoByStatusSpecification(EnumContentStatus.Draft);

    // Act
    bool result = spec.IsSatisfiedBy(video);

    // Assert
    result.Should().BeTrue();
}

/// <summary>
/// Verifies that a published video does not satisfy the Draft specification.
/// </summary>
[Fact]
public void VideoByStatusSpecification_WithDifferentStatus_ShouldReturnFalse()
{
    // Arrange
    VideoEntity video = VideoFactory.CreatePublished(categoryId);
    var spec = new VideoByStatusSpecification(EnumContentStatus.Draft);

    // Act
    bool result = spec.IsSatisfiedBy(video);

    // Assert
    result.Should().BeFalse();
}

Fast, deterministic, no database setup. I can verify that ActiveVideoSpecification correctly excludes archived and rejected videos without spinning up an in-memory database or mocking anything.

For specifications that use EF.Functions.ILike (which only works with a real PostgreSQL provider), I at least test that the expression compiles:

/// <summary>
/// Verifies that the search specification produces a valid compilable expression.
/// ILike requires PostgreSQL, so we only verify compilation here.
/// </summary>
[Fact]
public void VideoSearchSpecification_ShouldCompileExpression()
{
    // Arrange
    var spec = new VideoSearchSpecification("test");

    // Act
    Func<VideoEntity, bool> predicate = spec.ToExpression().Compile();

    // Assert
    predicate.Should().NotBeNull();
}

Not a full integration test, but it catches expression tree errors at compile time rather than at runtime.

What I Got Out of It

After rolling this out across all modules, a few things changed:

Repository methods got shorter. Instead of growing a new method for every filter combination, each repository has a small set of generic methods that accept specifications. The GetAllAsync method on every repository looks almost identical.
The filtering logic is reusable. The VideoSearchSpecification works whether you call it from the admin panel, a public API, or a background job. Same class, same SQL, same behavior.
New filters are trivial to add. When I needed an ActiveVideoSpecification to exclude archived and rejected videos from a dropdown, I created one small class and was done. No repository changes. No handler changes. Just a new specification.
Composition works naturally. Need active videos in a specific category? activeSpec.And(categorySpec). Need published or featured videos? publishedSpec.Or(featuredSpec). The And, Or, and Not operators handle it.
Unit tests are fast. I have nearly 100 specification tests across the project and they all run in under a second because none of them hit a database.

The pattern is not free. You end up with more files. A module that had one repository class now has a specifications folder with 5 to 10 small classes, plus a builder. But each file is 10 to 15 lines, does one thing, and is independently testable. I will take that over a 200-line repository method with nested conditionals any day.