test: Add unit tests, controller ctor; fix timestamp logic

Add numerous unit tests across Themerr.Tests to increase coverage and validate edge cases (controller ReplaceTheme, manager Sync and Replace behaviors, ContinueDownload exception handling, legacy path candidates, database path/migration, and path handling for files without extension). Introduce SetThemerrPluginInstance test helper. Add an explicit ThemerrController constructor overload. Update ThemerrManager to clear DownloadedTimestampUtc when the current theme provider is not Themerr to avoid preserving irrelevant timestamps. Also add doxygen to .readthedocs.yaml apt_packages so source API docs can be generated.

Author: ReenigneArcher

.readthedocs.yaml

@@ -12,6 +12,7 @@ build:
   tools:
     python: "3.14"
   apt_packages:
+    - doxygen  # required to generate source API docs
     - graphviz  # required to build diagrams
   jobs:
     post_build:

Jellyfin.Plugin.Themerr.Tests/TestThemerrController.cs

@@ -2,6 +2,7 @@
 using System.Collections;
 using System.Collections.Generic;
 using System.IO;
+using Jellyfin.Plugin.Themerr;
 using Jellyfin.Plugin.Themerr.Api;
 using Jellyfin.Plugin.Themerr.Storage;
 using MediaBrowser.Common.Configuration;
@@ -147,4 +148,71 @@ public async Task TestReplaceThemeNotFound()
         var result = await _controller.ReplaceTheme(Guid.NewGuid());
         Assert.IsType<NotFoundResult>(result);
     }
+
+    /// <summary>
+    /// Test ReplaceTheme returns 204 when the item theme is replaced.
+    /// </summary>
+    [Fact]
+    [Trait("Category", "Unit")]
+    public async Task TestReplaceThemeNoContent()
+    {
+        var tempPath = Path.Combine(Path.GetTempPath(), "ThemerrJellyfinTests", Guid.NewGuid().ToString("N"));
+        Directory.CreateDirectory(tempPath);
+        var movie = new Movie
+        {
+            Name = "Controller Replace",
+            Path = Path.Combine(tempPath, "Controller Replace (1970).mp4"),
+            ProductionYear = 1970,
+            ProviderIds = new Dictionary<string, string> { { MetadataProvider.Tmdb.ToString(), "controller-replace" } },
+        };
+        var themePath = ThemerrManager.GetThemePath(movie);
+        var audioStubPath = Path.Combine(Directory.GetCurrentDirectory(), "data", "audio_stub.mp3");
+        var repository = new ThemerrRepository(
+            Path.Combine(tempPath, "themerr.db"),
+            new Mock<ILogger>().Object);
+        repository.Save(movie, new ThemerrMediaItemSaveOptions
+        {
+            ThemePath = themePath,
+            ThemeProvider = ThemerrThemeProvider.User,
+            InThemerrDb = true,
+            InThemerrDbCheckedUtc = DateTime.UtcNow,
+            YoutubeThemeUrl = "https://www.youtube.com/watch?v=controller-replace",
+        });
+
+        var mockApplicationPaths = TestHelper.GetMockApplicationPaths(tempPath);
+        var mockLibraryManager = new Mock<ILibraryManager>();
+        mockLibraryManager
+            .Setup(x => x.GetItemById(movie.Id))
+            .Returns(movie);
+        var mockYoutubeClient = new Mock<IYoutubeClientWrapper>();
+        mockYoutubeClient
+            .Setup(x => x.DownloadAudioAsync(It.IsAny<string>(), It.IsAny<string>()))
+            .Returns<string, string>((_, destination) =>
+            {
+                File.Copy(audioStubPath, destination, true);
+                return Task.CompletedTask;
+            });
+        var manager = new ThemerrManager(
+            mockApplicationPaths.Object,
+            mockLibraryManager.Object,
+            new Mock<ILogger<ThemerrManager>>().Object,
+            mockYoutubeClient.Object,
+            repository);
+        var controller = new ThemerrController(manager, new Mock<ILogger<ThemerrController>>().Object);
+
+        try
+        {
+            var result = await controller.ReplaceTheme(movie.Id);
+
+            Assert.IsType<NoContentResult>(result);
+            Assert.True(File.Exists(themePath));
+        }
+        finally
+        {
+            if (File.Exists(themePath))
+            {
+                File.Delete(themePath);
+            }
+        }
+    }
 }

Jellyfin.Plugin.Themerr.Tests/TestThemerrManager.cs

@@ -433,6 +433,15 @@ private static void CreateThemerrPluginInstance(bool backupUserSuppliedTheme = t
         plugin.Configuration.BackupUserSuppliedTheme = backupUserSuppliedTheme;
     }
 
+    private static void SetThemerrPluginInstance(ThemerrPlugin? plugin)
+    {
+        var instanceField = typeof(ThemerrPlugin).GetField(
+            "<Instance>k__BackingField",
+            BindingFlags.NonPublic | BindingFlags.Static);
+        Assert.NotNull(instanceField);
+        instanceField.SetValue(null, plugin);
+    }
+
     private static ThemerrManager CreateThemerrManagerWithFailingYoutubeAndItemById(
         BaseItem item,
         ThemerrRepository? themerrRepository = null,
@@ -969,6 +978,17 @@ private async Task TestGetThemeProvider(BaseItem item)
         Assert.Equal(ThemerrThemeProvider.Themerr, themeProvider);
     }
 
+    [Fact]
+    [Trait("Category", "Unit")]
+    private async Task TestGetThemeProviderUnsupportedItem()
+    {
+        var manager = CreateThemerrManager();
+
+        var themeProvider = await manager.GetThemeProvider(new Audio { Name = "Unsupported Theme Provider" });
+
+        Assert.Null(themeProvider);
+    }
+
     [Fact]
     [Trait("Category", "Unit")]
     private void TestContinueDownload()
@@ -1360,6 +1380,55 @@ private async Task TestSyncLibraryItemTracksUserThemeAndCachedThemerrDbUrl()
         Assert.Null(syncedItem.ThemeHash);
     }
 
+    [Fact]
+    [Trait("Category", "Unit")]
+    private async Task TestSyncLibraryItemPreservesThemerrDownloadedTimestamp()
+    {
+        var repository = CreateThemerrRepository();
+        var manager = CreateThemerrManager(repository);
+        var tempPath = CreateTempDirectory();
+        var item = CreateMovie("sync-themerr-timestamp");
+        item.Path = Path.Combine(tempPath, "Test Movie (1970).mp4");
+        var themePath = ThemerrManager.GetThemePath(item);
+        var downloadedTimestampUtc = DateTime.UtcNow.AddMinutes(-10);
+
+        File.Copy(
+            Path.Combine(Directory.GetCurrentDirectory(), "data", "audio_stub.mp3"),
+            themePath,
+            true);
+        var themeHash = ThemerrManager.GetThemeHash(themePath);
+
+        repository.Save(
+            item,
+            new ThemerrMediaItemSaveOptions
+            {
+                ThemePath = themePath,
+                ThemeHash = themeHash,
+                ThemeHashAlgorithm = ThemerrThemeHasher.CurrentAlgorithm,
+                ThemeProvider = ThemerrThemeProvider.Themerr,
+                DownloadedTimestampUtc = downloadedTimestampUtc,
+                InThemerrDb = true,
+                InThemerrDbCheckedUtc = DateTime.UtcNow,
+                YoutubeThemeUrl = "https://www.youtube.com/watch?v=sync-themerr-timestamp",
+            });
+
+        try
+        {
+            var syncedItem = await manager.SyncLibraryItem(item);
+
+            Assert.NotNull(syncedItem);
+            Assert.Equal(ThemerrThemeProvider.Themerr, syncedItem.ThemeProvider);
+            Assert.Equal(downloadedTimestampUtc, syncedItem.DownloadedTimestampUtc);
+        }
+        finally
+        {
+            if (File.Exists(themePath))
+            {
+                File.Delete(themePath);
+            }
+        }
+    }
+
     [Theory]
     [Trait("Category", "Unit")]
     [MemberData(nameof(FixtureJellyfinServer.MockItemsData), MemberType = typeof(FixtureJellyfinServer))]
@@ -1903,6 +1972,109 @@ private async Task TestReplaceWithThemerThemeNoBackupWhenNoExistingTheme()
         }
     }
 
+    /// <summary>
+    /// Test that ReplaceWithThemerTheme skips backup when the plugin instance is unavailable.
+    /// </summary>
+    [Fact]
+    [Trait("Category", "Unit")]
+    private async Task TestReplaceWithThemerThemeNoBackupWhenPluginInstanceMissing()
+    {
+        var previousPlugin = ThemerrPlugin.Instance;
+        SetThemerrPluginInstance(null);
+
+        var movie = CreateMovie("backup-plugin-missing");
+        var tempPath = CreateTempDirectory();
+        movie.Path = Path.Combine(tempPath, "Test Movie (1970).mp4");
+
+        var repository = CreateThemerrRepository();
+        var manager = CreateThemerrManagerWithMockYoutubeAndItemById(movie, repository);
+        var themePath = ThemerrManager.GetThemePath(movie);
+        var backupPath = Path.Combine(Path.GetDirectoryName(themePath)!, "theme.backup.mp3");
+
+        File.Copy(Path.Combine(Directory.GetCurrentDirectory(), "data", "audio_stub.mp3"), themePath, true);
+
+        repository.Save(movie, new ThemerrMediaItemSaveOptions
+        {
+            ThemePath = themePath,
+            ThemeProvider = ThemerrThemeProvider.User,
+            InThemerrDb = true,
+            InThemerrDbCheckedUtc = DateTime.UtcNow,
+            YoutubeThemeUrl = "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
+        });
+
+        try
+        {
+            var result = await manager.ReplaceWithThemerTheme(movie.Id);
+            Assert.True(result);
+            Assert.True(File.Exists(themePath));
+            Assert.False(File.Exists(backupPath));
+        }
+        finally
+        {
+            SetThemerrPluginInstance(previousPlugin);
+            if (File.Exists(themePath))
+            {
+                File.Delete(themePath);
+            }
+
+            if (File.Exists(backupPath))
+            {
+                File.Delete(backupPath);
+            }
+        }
+    }
+
+    /// <summary>
+    /// Test that ReplaceWithThemerTheme returns false without restore work when no backup exists.
+    /// </summary>
+    [Fact]
+    [Trait("Category", "Unit")]
+    private async Task TestReplaceWithThemerThemeDownloadFailureWithoutBackup()
+    {
+        var previousPlugin = ThemerrPlugin.Instance;
+        CreateThemerrPluginInstance(backupUserSuppliedTheme: false);
+
+        var movie = CreateMovie("backup-failure-no-backup");
+        var tempPath = CreateTempDirectory();
+        movie.Path = Path.Combine(tempPath, "Test Movie (1970).mp4");
+
+        var repository = CreateThemerrRepository();
+        var manager = CreateThemerrManagerWithFailingYoutubeAndItemById(movie, repository);
+        var themePath = ThemerrManager.GetThemePath(movie);
+        var backupPath = Path.Combine(Path.GetDirectoryName(themePath)!, "theme.backup.mp3");
+
+        repository.Save(movie, new ThemerrMediaItemSaveOptions
+        {
+            ThemePath = themePath,
+            ThemeProvider = ThemerrThemeProvider.User,
+            InThemerrDb = true,
+            InThemerrDbCheckedUtc = DateTime.UtcNow,
+            YoutubeThemeUrl = "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
+        });
+
+        try
+        {
+            var result = await manager.ReplaceWithThemerTheme(movie.Id);
+
+            Assert.False(result);
+            Assert.False(File.Exists(themePath));
+            Assert.False(File.Exists(backupPath));
+        }
+        finally
+        {
+            SetThemerrPluginInstance(previousPlugin);
+            if (File.Exists(themePath))
+            {
+                File.Delete(themePath);
+            }
+
+            if (File.Exists(backupPath))
+            {
+                File.Delete(backupPath);
+            }
+        }
+    }
+
     /// <summary>
     /// Test that ReplaceWithThemerTheme restores the original theme from backup when the download fails.
     /// </summary>
@@ -1980,6 +2152,52 @@ private void TestContinueDownloadUsesExistingThemeSongPath()
         Assert.False(manager.ContinueDownload(item, missingThemePath));
     }
 
+    [Fact]
+    [Trait("Category", "Unit")]
+    private void TestContinueDownloadIgnoresNullReferenceFromThemeSongs()
+    {
+        var repository = CreateThemerrRepository();
+        var item = CreateMovie("theme-song-null-reference");
+        var missingThemePath = Path.Combine(CreateTempDirectory(), "missing-theme.mp3");
+        var manager = CreateThemerrManager(
+            repository,
+            themeSongProvider: _ => throw new NullReferenceException("Simulated theme song failure"));
+
+        Assert.True(manager.ContinueDownload(item, missingThemePath));
+    }
+
+    [Fact]
+    [Trait("Category", "Unit")]
+    private void TestContinueDownloadIgnoresThemeSongExceptionWithoutLogger()
+    {
+        var repository = CreateThemerrRepository();
+        var item = CreateMovie("theme-song-null-logger");
+        var missingThemePath = Path.Combine(CreateTempDirectory(), "missing-theme.mp3");
+        var manager = new ThemerrManager(
+            TestHelper.GetMockApplicationPaths().Object,
+            new Mock<ILibraryManager>().Object,
+            null!,
+            themerrRepository: repository,
+            httpClient: CreateThemerrDbHttpClient(),
+            themeSongProvider: _ => throw new NullReferenceException("Simulated theme song failure"));
+
+        Assert.True(manager.ContinueDownload(item, missingThemePath));
+    }
+
+    [Fact]
+    [Trait("Category", "Unit")]
+    private void TestContinueDownloadPropagatesUnexpectedThemeSongException()
+    {
+        var repository = CreateThemerrRepository();
+        var item = CreateMovie("theme-song-unexpected-exception");
+        var missingThemePath = Path.Combine(CreateTempDirectory(), "missing-theme.mp3");
+        var manager = CreateThemerrManager(
+            repository,
+            themeSongProvider: _ => throw new ArgumentException("Simulated unexpected theme song failure"));
+
+        Assert.Throws<ArgumentException>(() => manager.ContinueDownload(item, missingThemePath));
+    }
+
     [Fact]
     [Trait("Category", "Unit")]
     private void TestLegacyThemerrDataPathCandidatesIncludeRawDirectoryCandidate()
@@ -2011,6 +2229,8 @@ private void TestIsMatchingMediaDirectoryHandlesEmptyAndMismatchedNames()
         var tempPath = CreateTempDirectory();
         var matchingDirectory = Path.Combine(tempPath, "Empty Name (1970)");
         var mismatchedDirectory = Path.Combine(tempPath, "Different Title (1970)");
+        var yearlessDirectory = Path.Combine(tempPath, "Yearless Title");
+        var missingYearDirectory = Path.Combine(tempPath, "Test Movie matching-media-directory (1980)");
         Directory.CreateDirectory(matchingDirectory);
         Directory.CreateDirectory(mismatchedDirectory);
         var method = typeof(ThemerrManager).GetMethod(
@@ -2036,9 +2256,29 @@ private void TestIsMatchingMediaDirectoryHandlesEmptyAndMismatchedNames()
                 CreateMovie("matching-media-directory"),
                 mismatchedDirectory,
             })!;
+        var yearlessResult = (bool)method.Invoke(
+            manager,
+            new object[]
+            {
+                new Movie
+                {
+                    Name = "Yearless Title",
+                    ProductionYear = null,
+                },
+                yearlessDirectory,
+            })!;
+        var missingYearResult = (bool)method.Invoke(
+            manager,
+            new object[]
+            {
+                CreateMovie("matching-media-directory"),
+                missingYearDirectory,
+            })!;
 
         Assert.False(emptyNameResult);
         Assert.False(mismatchedNameResult);
+        Assert.True(yearlessResult);
+        Assert.False(missingYearResult);
     }
 
     [Fact]