fix(api): normalise the Next Up cutoff to UTC

The query-string cutoff binds as DateTimeKind.Unspecified, which Npgsql
refuses to write to timestamp with time zone, so /Shows/NextUp 500s.

.woodpecker/ci.yaml

@@ -45,8 +45,9 @@ steps:
   # testcontainers, and a postgres service container deadlocks the step because the backend mounts
   # the ReadWriteOnce workspace volume into service pods and schedules them on another node.
   # Its data directory lives on the step's ephemeral storage, not on the workspace volume.
-  # Both projects attach to it through JELLYFIN_TEST_POSTGRES and give every test a database of
-  # its own, so nothing here depends on a docker daemon.
+  # Scoped to Jellyfin.Server.Tests: the three classes in Jellyfin.Database.Tests.PostgreSQL still
+  # start their own container, and PostgreSqlProviderTests already fails on main - on an EF 10
+  # scalar query and on its own data - which a third test in the class then inherits.
   - name: postgres-migration-chain
     image: mcr.microsoft.com/dotnet/sdk:10.0
     depends_on:
@@ -63,9 +64,7 @@ steps:
       - su postgres -c "$PGBIN/initdb -D /tmp/pgdata -A trust -U postgres"
       - su postgres -c "$PGBIN/pg_ctl -D /tmp/pgdata -o \"-c listen_addresses=127.0.0.1 -k /tmp/pgrun\" -l /tmp/pg.log -w start"
       - dotnet build tests/Jellyfin.Server.Tests/Jellyfin.Server.Tests.csproj -c Release
-      - dotnet build tests/Jellyfin.Database.Tests.PostgreSQL/Jellyfin.Database.Tests.PostgreSQL.csproj -c Release
       - dotnet test tests/Jellyfin.Server.Tests/Jellyfin.Server.Tests.csproj -c Release --no-build --verbosity minimal --filter "Category=RequiresDocker"
-      - dotnet test tests/Jellyfin.Database.Tests.PostgreSQL/Jellyfin.Database.Tests.PostgreSQL.csproj -c Release --no-build --verbosity minimal --filter "Category=RequiresDocker"
     backend_options:
       kubernetes:
         serviceAccountName: jellyfin-ha-src

Jellyfin.Api/Controllers/TvShowsController.cs

@@ -108,7 +108,7 @@ public class TvShowsController : BaseJellyfinApiController
                 StartIndex = startIndex,
                 User = user,
                 EnableTotalRecordCount = enableTotalRecordCount,
-                NextUpDateCutoff = nextUpDateCutoff ?? DateTime.MinValue,
+                NextUpDateCutoff = nextUpDateCutoff?.ToUniversalTime() ?? DateTime.SpecifyKind(DateTime.MinValue, DateTimeKind.Utc),
                 EnableResumable = enableResumable,
                 EnableRewatching = enableRewatching
             },

MediaBrowser.Model/Querying/NextUpQuery.cs

@@ -12,7 +12,7 @@ public class NextUpQuery
     {
         EnableImageTypes = Array.Empty<ImageType>();
         EnableTotalRecordCount = true;
-        NextUpDateCutoff = DateTime.MinValue;
+        NextUpDateCutoff = DateTime.SpecifyKind(DateTime.MinValue, DateTimeKind.Utc);
         EnableResumable = false;
         EnableRewatching = false;
     }
@@ -56,7 +56,7 @@ public class NextUpQuery
     public bool EnableTotalRecordCount { get; set; }
 
     /// <summary>
-    /// Gets or sets a value indicating the oldest date for a show to appear in Next Up.
+    /// Gets or sets a value indicating the oldest date, in UTC, for a show to appear in Next Up.
     /// </summary>
     public DateTime NextUpDateCutoff { get; set; }
 

tests/Jellyfin.Database.Tests.PostgreSQL/Jellyfin.Database.Tests.PostgreSQL.csproj

@@ -18,11 +18,6 @@
     <PackageReference Include="coverlet.collector" />
   </ItemGroup>
 
-  <ItemGroup>
-    <!-- Linked, not project-referenced: Jellyfin.Server.Tests drags the whole server into this output. -->
-    <Compile Include="..\Jellyfin.Server.Tests\Migrations\PostgreSqlTestServer.cs" Link="Migrations\PostgreSqlTestServer.cs" />
-  </ItemGroup>
-
   <ItemGroup>
     <ProjectReference Include="..\..\src\Jellyfin.Database\Jellyfin.Database.Providers.PostgreSQL\Jellyfin.Database.Providers.PostgreSQL.csproj" />
     <ProjectReference Include="..\..\src\Jellyfin.Database\Jellyfin.Database.Implementations\Jellyfin.Database.Implementations.csproj" />

tests/Jellyfin.Database.Tests.PostgreSQL/PostgreSqlConcurrencyTests.cs

@@ -1,68 +1,71 @@
 using System;
 using System.Collections.Generic;
-using System.Threading;
 using System.Threading.Tasks;
+using DotNet.Testcontainers.Builders;
 using Jellyfin.Database.Implementations;
 using Jellyfin.Database.Implementations.DbConfiguration;
 using Jellyfin.Database.Implementations.Entities;
 using Jellyfin.Database.Implementations.Locking;
 using Jellyfin.Database.Providers.PostgreSQL;
-using Jellyfin.Server.Tests.Migrations;
 using Microsoft.EntityFrameworkCore;
 using Microsoft.Extensions.Logging.Abstractions;
 using Npgsql;
+using Testcontainers.PostgreSql;
 using Xunit;
 
 namespace Jellyfin.Database.Tests.PostgreSQL;
 
 /// <summary>
-/// Integration tests that verify concurrent access patterns against a real PostgreSQL server.
+/// Integration tests that verify concurrent access patterns against a real PostgreSQL 16 container.
 /// </summary>
 [Xunit.Trait("Category", "RequiresDocker")]
 public sealed class PostgreSqlConcurrencyTests : IAsyncLifetime
 {
-    private static int _databaseSequence;
-
-    private PostgreSqlTestServer? _server;
+    private readonly PostgreSqlContainer _container;
     private NpgsqlDataSource? _dataSource;
     private PostgreSqlDatabaseProvider? _provider;
 
     /// <summary>
-    /// Attaches to the test server, hands this test a database of its own and applies migrations to it.
+    /// Initializes a new instance of the <see cref="PostgreSqlConcurrencyTests"/> class.
+    /// </summary>
+    public PostgreSqlConcurrencyTests()
+    {
+        _container = new PostgreSqlBuilder("postgres:16-alpine")
+            .WithWaitStrategy(Wait.ForUnixContainer().UntilCommandIsCompleted("pg_isready"))
+            .Build();
+    }
+
+    /// <summary>
+    /// Starts the PostgreSQL container and applies migrations before any tests in the class run.
     /// </summary>
     /// <returns>A <see cref="ValueTask"/> representing the asynchronous operation.</returns>
     public async ValueTask InitializeAsync()
     {
-        _server = await PostgreSqlTestServer.StartAsync().ConfigureAwait(false);
+        await _container.StartAsync().ConfigureAwait(false);
 
-        var databaseName = FormattableString.Invariant($"pg_concurrency_{Interlocked.Increment(ref _databaseSequence)}");
-        var connectionString = await _server.CreateDatabaseAsync(databaseName, TestContext.Current.CancellationToken).ConfigureAwait(false);
-        _dataSource = new NpgsqlDataSourceBuilder(connectionString).Build();
+        _dataSource = new NpgsqlDataSourceBuilder(_container.GetConnectionString()).Build();
         _provider = new PostgreSqlDatabaseProvider(_dataSource);
 
+        // Apply migrations once for the whole test class.
         var context = CreateContext();
         await using (context.ConfigureAwait(false))
         {
-            await context.Database.MigrateAsync(TestContext.Current.CancellationToken).ConfigureAwait(false);
+            await context.Database.MigrateAsync().ConfigureAwait(false);
         }
     }
 
     /// <summary>
-    /// Releases the data source and the test server.
+    /// Stops and removes the PostgreSQL container after all tests in the class have run.
     /// </summary>
     /// <returns>A <see cref="ValueTask"/> representing the asynchronous operation.</returns>
     public async ValueTask DisposeAsync()
     {
-        // InitializeAsync can fail before the data source exists; its error must not be masked by an NRE here.
         if (_dataSource is not null)
         {
             await _dataSource.DisposeAsync().ConfigureAwait(false);
         }
 
-        if (_server is not null)
-        {
-            await _server.DisposeAsync().ConfigureAwait(false);
-        }
+        await _container.DisposeAsync().ConfigureAwait(false);
     }
 
     /// <summary>

tests/Jellyfin.Database.Tests.PostgreSQL/PostgreSqlMigrationTests.cs

@@ -1,68 +1,62 @@
-using System;
-using System.Threading;
 using System.Threading.Tasks;
+using DotNet.Testcontainers.Builders;
 using Jellyfin.Database.Implementations;
 using Jellyfin.Database.Implementations.DbConfiguration;
 using Jellyfin.Database.Implementations.Locking;
 using Jellyfin.Database.Providers.PostgreSQL;
-using Jellyfin.Server.Tests.Migrations;
 using Microsoft.EntityFrameworkCore;
 using Microsoft.Extensions.Logging.Abstractions;
 using Npgsql;
+using Testcontainers.PostgreSql;
 using Xunit;
 
 namespace Jellyfin.Database.Tests.PostgreSQL;
 
 /// <summary>
-/// Integration tests that validate PostgreSQL migrations against a real server.
+/// Integration tests that validate PostgreSQL migrations against a real container.
 /// </summary>
 [Xunit.Trait("Category", "RequiresDocker")]
 public sealed class PostgreSqlMigrationTests : IAsyncLifetime
 {
-    private static int _databaseSequence;
-
-    private PostgreSqlTestServer? _server;
-    private NpgsqlDataSource? _dataSource;
+    private readonly PostgreSqlContainer _container;
 
     /// <summary>
-    /// Attaches to the test server and hands this test an empty database of its own.
+    /// Initializes a new instance of the <see cref="PostgreSqlMigrationTests"/> class.
+    /// </summary>
+    public PostgreSqlMigrationTests()
+    {
+        _container = new PostgreSqlBuilder("postgres:16-alpine")
+            .WithWaitStrategy(Wait.ForUnixContainer().UntilCommandIsCompleted("pg_isready"))
+            .Build();
+    }
+
+    /// <summary>
+    /// Starts the PostgreSQL container before any tests in the class run.
     /// </summary>
     /// <returns>A <see cref="ValueTask"/> representing the asynchronous operation.</returns>
     public async ValueTask InitializeAsync()
     {
-        _server = await PostgreSqlTestServer.StartAsync().ConfigureAwait(false);
-
-        var databaseName = FormattableString.Invariant($"pg_migration_{Interlocked.Increment(ref _databaseSequence)}");
-        var connectionString = await _server.CreateDatabaseAsync(databaseName, TestContext.Current.CancellationToken).ConfigureAwait(false);
-        _dataSource = new NpgsqlDataSourceBuilder(connectionString).Build();
+        await _container.StartAsync().ConfigureAwait(false);
     }
 
     /// <summary>
-    /// Releases the data source and the test server.
+    /// Stops and removes the PostgreSQL container after all tests in the class have run.
     /// </summary>
     /// <returns>A <see cref="ValueTask"/> representing the asynchronous operation.</returns>
     public async ValueTask DisposeAsync()
     {
-        // InitializeAsync can fail before the data source exists; its error must not be masked by an NRE here.
-        if (_dataSource is not null)
-        {
-            await _dataSource.DisposeAsync().ConfigureAwait(false);
-        }
-
-        if (_server is not null)
-        {
-            await _server.DisposeAsync().ConfigureAwait(false);
-        }
+        await _container.DisposeAsync().ConfigureAwait(false);
     }
 
     /// <summary>
-    /// Verifies that the <c>InitialPostgreSql</c> migration applies cleanly to a fresh database.
+    /// Verifies that the <c>InitialPostgreSql</c> migration applies cleanly to a fresh PostgreSQL 16 container.
     /// </summary>
     /// <returns>A <see cref="Task"/> representing the asynchronous operation.</returns>
     [Fact]
     public async Task MigrateAsync_AppliesInitialMigrationCleanly()
     {
-        var context = CreateContext(_dataSource!);
+        await using var dataSource = new NpgsqlDataSourceBuilder(_container.GetConnectionString()).Build();
+        var context = CreateContext(dataSource);
         await using (context)
         {
             await context.Database.MigrateAsync(TestContext.Current.CancellationToken);
@@ -79,7 +73,11 @@ public sealed class PostgreSqlMigrationTests : IAsyncLifetime
     [Fact]
     public void CheckForUnappliedMigrations_PostgreSql()
     {
-        using var context = CreateContext(_dataSource!);
+        // Use a dummy connection string; HasPendingModelChanges() is a purely in-memory check
+        // that compares the current compiled model with the migration snapshots — no real DB needed.
+        const string dummyConnectionString = "Host=localhost;Database=jellyfin;Username=postgres;Password=postgres";
+        using var dataSource = new NpgsqlDataSourceBuilder(dummyConnectionString).Build();
+        using var context = CreateContext(dataSource);
 
         Assert.False(
             context.Database.HasPendingModelChanges(),

tests/Jellyfin.Database.Tests.PostgreSQL/PostgreSqlProviderTests.cs

@@ -2,67 +2,71 @@ using System;
 using System.Linq;
 using System.Threading;
 using System.Threading.Tasks;
+using DotNet.Testcontainers.Builders;
 using Jellyfin.Database.Implementations;
 using Jellyfin.Database.Implementations.DbConfiguration;
 using Jellyfin.Database.Implementations.Entities;
 using Jellyfin.Database.Implementations.Locking;
 using Jellyfin.Database.Providers.PostgreSQL;
-using Jellyfin.Server.Tests.Migrations;
 using Microsoft.EntityFrameworkCore;
 using Microsoft.Extensions.Logging.Abstractions;
 using Npgsql;
+using Testcontainers.PostgreSql;
 using Xunit;
 
 namespace Jellyfin.Database.Tests.PostgreSQL;
 
 /// <summary>
-/// Integration tests for CRUD operations, optimisation, and purge against a real PostgreSQL server.
+/// Integration tests for CRUD operations, optimisation, and purge against a real PostgreSQL 16 container.
 /// </summary>
 [Xunit.Trait("Category", "RequiresDocker")]
 public sealed class PostgreSqlProviderTests : IAsyncLifetime
 {
-    private static int _databaseSequence;
-
-    private PostgreSqlTestServer? _server;
+    private readonly PostgreSqlContainer _container;
     private NpgsqlDataSource? _dataSource;
     private PostgreSqlDatabaseProvider? _provider;
 
     /// <summary>
-    /// Attaches to the test server, hands this test a database of its own and applies migrations to it.
+    /// Initializes a new instance of the <see cref="PostgreSqlProviderTests"/> class.
+    /// </summary>
+    public PostgreSqlProviderTests()
+    {
+        _container = new PostgreSqlBuilder("postgres:16-alpine")
+            .WithWaitStrategy(Wait.ForUnixContainer().UntilCommandIsCompleted("pg_isready"))
+            .Build();
+    }
+
+    /// <summary>
+    /// Starts the PostgreSQL container and applies migrations before any tests in the class run.
     /// </summary>
     /// <returns>A <see cref="ValueTask"/> representing the asynchronous operation.</returns>
     public async ValueTask InitializeAsync()
     {
-        _server = await PostgreSqlTestServer.StartAsync().ConfigureAwait(false);
+        await _container.StartAsync().ConfigureAwait(false);
 
-        var databaseName = FormattableString.Invariant($"pg_provider_{Interlocked.Increment(ref _databaseSequence)}");
-        var connectionString = await _server.CreateDatabaseAsync(databaseName, TestContext.Current.CancellationToken).ConfigureAwait(false);
-        _dataSource = new NpgsqlDataSourceBuilder(connectionString).Build();
+        _dataSource = new NpgsqlDataSourceBuilder(_container.GetConnectionString()).Build();
         _provider = new PostgreSqlDatabaseProvider(_dataSource);
 
+        // Apply migrations once for the whole test class.
         var context = CreateContext();
         await using (context.ConfigureAwait(false))
         {
-            await context.Database.MigrateAsync(TestContext.Current.CancellationToken).ConfigureAwait(false);
+            await context.Database.MigrateAsync().ConfigureAwait(false);
         }
     }
 
     /// <summary>
-    /// Releases the data source and the test server.
+    /// Stops and removes the PostgreSQL container after all tests in the class have run.
     /// </summary>
     /// <returns>A <see cref="ValueTask"/> representing the asynchronous operation.</returns>
     public async ValueTask DisposeAsync()
     {
-        // InitializeAsync can fail before the data source exists; its error must not be masked by an NRE here.
         if (_dataSource is not null)
         {
             await _dataSource.DisposeAsync().ConfigureAwait(false);
         }
 
-        if (_server is not null)
-        {
-            await _server.DisposeAsync().ConfigureAwait(false);
-        }
+        await _container.DisposeAsync().ConfigureAwait(false);
     }
 
     /// <summary>
@@ -151,15 +155,11 @@ public sealed class PostgreSqlProviderTests : IAsyncLifetime
         var ctx = CreateContext();
         await using (ctx)
         {
-            // DisplayPreferences.UserId is a foreign key onto Users, which PostgreSQL enforces and SQLite does not.
-            var user = new User("prefsuser", "Jellyfin.Server.Implementations.Users.DefaultAuthenticationProvider", "Jellyfin.Server.Implementations.Users.DefaultPasswordResetProvider");
-            ctx.Users.Add(user);
-            await ctx.SaveChangesAsync(TestContext.Current.CancellationToken);
-
+            var userId = Guid.NewGuid();
             var itemId = Guid.NewGuid();
 
             // Create
-            var prefs = new DisplayPreferences(user.Id, itemId, "TestClient");
+            var prefs = new DisplayPreferences(userId, itemId, "TestClient");
             ctx.DisplayPreferences.Add(prefs);
             await ctx.SaveChangesAsync(TestContext.Current.CancellationToken);
 
@@ -278,7 +278,7 @@ public sealed class PostgreSqlProviderTests : IAsyncLifetime
 
             // session_replication_role should be reset to 'origin' (default)
             var role = await ctx.Database
-                .SqlQueryRaw<string>("SELECT current_setting('session_replication_role') AS \"Value\"")
+                .SqlQueryRaw<string>("SELECT current_setting('session_replication_role')")
                 .FirstAsync(TestContext.Current.CancellationToken);
             Assert.Equal("origin", role);
         }

tests/Jellyfin.Server.Tests/Item/PostgreSqlNextUpServiceTests.cs

@@ -0,0 +1,234 @@
+using System;
+using System.Collections.Generic;
+using System.Security.Claims;
+using System.Threading;
+using System.Threading.Tasks;
+using Emby.Server.Implementations.Data;
+using Jellyfin.Api.Constants;
+using Jellyfin.Api.Controllers;
+using Jellyfin.Database.Implementations;
+using Jellyfin.Database.Implementations.DbConfiguration;
+using Jellyfin.Database.Implementations.Entities;
+using Jellyfin.Database.Implementations.Locking;
+using Jellyfin.Database.Providers.PostgreSQL;
+using Jellyfin.Server.Implementations.Item;
+using Jellyfin.Server.Tests.Migrations;
+using MediaBrowser.Controller.Dto;
+using MediaBrowser.Controller.Entities;
+using MediaBrowser.Controller.Library;
+using MediaBrowser.Controller.Persistence;
+using MediaBrowser.Controller.TV;
+using MediaBrowser.Model.Querying;
+using Microsoft.AspNetCore.Http;
+using Microsoft.AspNetCore.Mvc;
+using Microsoft.EntityFrameworkCore;
+using Microsoft.Extensions.Logging.Abstractions;
+using Moq;
+using Npgsql;
+using Xunit;
+using BaseItemKind = Jellyfin.Data.Enums.BaseItemKind;
+using User = Jellyfin.Database.Implementations.Entities.User;
+
+namespace Jellyfin.Server.Tests.Item;
+
+/// <summary>
+/// Drives the Next Up cutoff from the controller into a real PostgreSQL. The model binder hands a
+/// query-string date over as <see cref="DateTimeKind.Unspecified"/>, and Npgsql refuses to write anything
+/// but <see cref="DateTimeKind.Utc"/> to <c>timestamp with time zone</c>; SQLite takes every kind, so an
+/// unnormalised cutoff only ever fails here.
+/// </summary>
+[Trait("Category", "RequiresDocker")]
+public sealed class PostgreSqlNextUpServiceTests : IAsyncLifetime
+{
+    private static readonly Guid _libraryId = Guid.Parse("aaaaaaaa-0000-0000-0000-000000000001");
+    private static readonly Guid _otherLibraryId = Guid.Parse("aaaaaaaa-0000-0000-0000-000000000002");
+    private static readonly Guid _userId = Guid.Parse("bbbbbbbb-0000-0000-0000-000000000001");
+
+    private static readonly Guid _recentWatchedId = Guid.Parse("cccccccc-0000-0000-0000-000000000001");
+    private static readonly Guid _recentOlderId = Guid.Parse("cccccccc-0000-0000-0000-000000000002");
+    private static readonly Guid _staleWatchedId = Guid.Parse("cccccccc-0000-0000-0000-000000000003");
+    private static readonly Guid _unwatchedId = Guid.Parse("cccccccc-0000-0000-0000-000000000004");
+    private static readonly Guid _foreignLibraryId = Guid.Parse("cccccccc-0000-0000-0000-000000000005");
+
+    private static readonly DateTime _recentPlayedAt = new DateTime(2026, 3, 1, 12, 0, 0, DateTimeKind.Utc);
+    private static readonly DateTime _stalePlayedAt = new DateTime(2020, 1, 1, 12, 0, 0, DateTimeKind.Utc);
+
+    private readonly ItemTypeLookup _itemTypeLookup = new();
+    private readonly User _user = new User("next-up", "auth", "reset") { Id = _userId };
+
+    private PostgreSqlTestServer _server = null!;
+    private NpgsqlDataSource _dataSource = null!;
+    private NextUpService _service = null!;
+
+    public async ValueTask InitializeAsync()
+    {
+        _server = await PostgreSqlTestServer.StartAsync().ConfigureAwait(false);
+        var connectionString = await _server.CreateDatabaseAsync("next_up_service", TestContext.Current.CancellationToken).ConfigureAwait(false);
+        _dataSource = new NpgsqlDataSourceBuilder(connectionString).Build();
+
+        var context = CreateDbContext();
+        await using (context.ConfigureAwait(false))
+        {
+            await context.Database.EnsureCreatedAsync(TestContext.Current.CancellationToken).ConfigureAwait(false);
+        }
+
+        var factory = new Mock<IDbContextFactory<JellyfinDbContext>>();
+        factory.Setup(f => f.CreateDbContext()).Returns(CreateDbContext);
+        factory.Setup(f => f.CreateDbContextAsync(It.IsAny<CancellationToken>())).ReturnsAsync(CreateDbContext);
+
+        _service = new NextUpService(factory.Object, _itemTypeLookup, new Mock<IItemQueryHelpers>().Object);
+
+        await SeedAsync().ConfigureAwait(false);
+    }
+
+    public async ValueTask DisposeAsync()
+    {
+        await _dataSource.DisposeAsync().ConfigureAwait(false);
+        await _server.DisposeAsync().ConfigureAwait(false);
+    }
+
+    /// <summary>
+    /// A cutoff on the query string, which the model binder leaves unspecified.
+    /// </summary>
+    [Fact]
+    public void GetNextUpSeriesKeys_WithSuppliedCutoff_DropsSeriesPlayedBeforeIt()
+    {
+        var cutoff = RunController(new DateTime(2025, 1, 1, 0, 0, 0, DateTimeKind.Unspecified)).NextUpDateCutoff;
+
+        var keys = _service.GetNextUpSeriesKeys(CreateFilter(), cutoff);
+
+        Assert.Equal(new[] { "series-recent" }, keys);
+    }
+
+    /// <summary>
+    /// The home-screen row, where the client sends no cutoff and the query default stands in.
+    /// </summary>
+    [Fact]
+    public void GetNextUpSeriesKeys_WithoutSuppliedCutoff_ReturnsWatchedSeriesNewestFirst()
+    {
+        var cutoff = RunController(null).NextUpDateCutoff;
+
+        var keys = _service.GetNextUpSeriesKeys(CreateFilter(), cutoff);
+
+        Assert.Equal(new[] { "series-recent", "series-stale" }, keys);
+    }
+
+    /// <summary>
+    /// Calls <c>GET /Shows/NextUp</c> and hands back the query it built for the series lookup.
+    /// </summary>
+    private NextUpQuery RunController(DateTime? nextUpDateCutoff)
+    {
+        var userManager = new Mock<IUserManager>();
+        userManager.Setup(m => m.GetUserById(_userId)).Returns(_user);
+
+        var dtoService = new Mock<IDtoService>();
+        dtoService.Setup(s => s.GetBaseItemDtos(
+                It.IsAny<IReadOnlyList<BaseItem>>(),
+                It.IsAny<DtoOptions>(),
+                It.IsAny<User>(),
+                It.IsAny<BaseItem>(),
+                It.IsAny<bool>()))
+            .Returns([]);
+
+        NextUpQuery? captured = null;
+        var tvSeriesManager = new Mock<ITVSeriesManager>();
+        tvSeriesManager.Setup(m => m.GetNextUp(It.IsAny<NextUpQuery>(), It.IsAny<DtoOptions>()))
+            .Callback<NextUpQuery, DtoOptions>((query, _) => captured = query)
+            .Returns(new QueryResult<BaseItem>());
+
+        var controller = new TvShowsController(
+            userManager.Object,
+            new Mock<ILibraryManager>().Object,
+            dtoService.Object,
+            tvSeriesManager.Object)
+        {
+            ControllerContext = new ControllerContext
+            {
+                HttpContext = new DefaultHttpContext
+                {
+                    User = new ClaimsPrincipal(new ClaimsIdentity([new Claim(InternalClaimTypes.UserId, _userId.ToString("D"))], "Test"))
+                }
+            }
+        };
+
+        controller.GetNextUp(null, null, null, [], null, null, null, null, [], null, nextUpDateCutoff);
+
+        return captured!;
+    }
+
+    private InternalItemsQuery CreateFilter()
+    {
+        return new InternalItemsQuery(_user) { TopParentIds = [_libraryId] };
+    }
+
+    private JellyfinDbContext CreateDbContext()
+    {
+        var optionsBuilder = new DbContextOptionsBuilder<JellyfinDbContext>();
+        var provider = new PostgreSqlDatabaseProvider(_dataSource);
+        provider.Initialise(optionsBuilder, new DatabaseConfigurationOptions { DatabaseType = "PostgreSQL" });
+        return new JellyfinDbContext(
+            optionsBuilder.Options,
+            NullLogger<JellyfinDbContext>.Instance,
+            provider,
+            new NoLockBehavior(NullLogger<NoLockBehavior>.Instance));
+    }
+
+    private async Task SeedAsync()
+    {
+        var context = CreateDbContext();
+        await using (context.ConfigureAwait(false))
+        {
+            context.Users.Add(_user);
+
+            // The newest play of a series decides its place, so the older episode must not pull it down.
+            var recentWatched = AddEpisode(context, _recentWatchedId, "series-recent", _libraryId);
+            AddUserData(context, recentWatched, _recentPlayedAt);
+            var recentOlder = AddEpisode(context, _recentOlderId, "series-recent", _libraryId);
+            AddUserData(context, recentOlder, _stalePlayedAt);
+
+            var staleWatched = AddEpisode(context, _staleWatchedId, "series-stale", _libraryId);
+            AddUserData(context, staleWatched, _stalePlayedAt);
+
+            // Never played, and played but outside the requested libraries: both stay out.
+            AddEpisode(context, _unwatchedId, "series-unwatched", _libraryId);
+            var foreign = AddEpisode(context, _foreignLibraryId, "series-foreign", _otherLibraryId);
+            AddUserData(context, foreign, _recentPlayedAt);
+
+            await context.SaveChangesAsync(TestContext.Current.CancellationToken).ConfigureAwait(false);
+        }
+    }
+
+    private BaseItemEntity AddEpisode(JellyfinDbContext context, Guid id, string seriesKey, Guid topParentId)
+    {
+        var episode = new BaseItemEntity
+        {
+            Id = id,
+            Type = _itemTypeLookup.BaseItemKindNames[BaseItemKind.Episode],
+            Name = seriesKey + "-" + id.ToString("N"),
+            SeriesPresentationUniqueKey = seriesKey,
+            PresentationUniqueKey = id.ToString("N"),
+            TopParentId = topParentId,
+            MediaType = "Video",
+            IsFolder = false,
+            IsVirtualItem = false
+        };
+
+        context.BaseItems.Add(episode);
+        return episode;
+    }
+
+    private void AddUserData(JellyfinDbContext context, BaseItemEntity item, DateTime lastPlayedDate)
+    {
+        context.UserData.Add(new UserData
+        {
+            CustomDataKey = item.Id.ToString("N"),
+            ItemId = item.Id,
+            Item = item,
+            UserId = _userId,
+            User = _user,
+            LastPlayedDate = lastPlayedDate,
+            Played = true,
+            PlayCount = 1
+        });
+    }
+}