reorganise unit tests

2 files changed, 842 insertions, 0 deletions

diff --git a/src/StardewModdingAPI.Tests/Core/ModResolverTests.cs b/src/StardewModdingAPI.Tests/Core/ModResolverTests.cs
new file mode 100644
index 00000000..efb1c348
--- /dev/null
+++ b/src/StardewModdingAPI.Tests/Core/ModResolverTests.cs
@@ -0,0 +1,486 @@
+using System;
+using System.Collections.Generic;
+using System.IO;
+using System.Linq;
+using Moq;
+using Newtonsoft.Json;
+using NUnit.Framework;
+using StardewModdingAPI.Framework;
+using StardewModdingAPI.Framework.Models;
+using StardewModdingAPI.Framework.ModLoading;
+using StardewModdingAPI.Framework.Serialisation;
+
+namespace StardewModdingAPI.Tests.Core
+{
+    /// <summary>Unit tests for <see cref="ModResolver"/>.</summary>
+    [TestFixture]
+    public class ModResolverTests
+    {
+        /*********
+        ** Unit tests
+        *********/
+        /****
+        ** ReadManifests
+        ****/
+        [Test(Description = "Assert that the resolver correctly returns an empty list if there are no mods installed.")]
+        public void ReadBasicManifest_NoMods_ReturnsEmptyList()
+        {
+            // arrange
+            string rootFolder = Path.Combine(Path.GetTempPath(), Guid.NewGuid().ToString("N"));
+            Directory.CreateDirectory(rootFolder);
+
+            // act
+            IModMetadata[] mods = new ModResolver().ReadManifests(rootFolder, new JsonHelper(), new ModCompatibility[0], new DisabledMod[0]).ToArray();
+
+            // assert
+            Assert.AreEqual(0, mods.Length, 0, $"Expected to find zero manifests, found {mods.Length} instead.");
+        }
+
+        [Test(Description = "Assert that the resolver correctly returns a failed metadata if there's an empty mod folder.")]
+        public void ReadBasicManifest_EmptyModFolder_ReturnsFailedManifest()
+        {
+            // arrange
+            string rootFolder = Path.Combine(Path.GetTempPath(), Guid.NewGuid().ToString("N"));
+            string modFolder = Path.Combine(rootFolder, Guid.NewGuid().ToString("N"));
+            Directory.CreateDirectory(modFolder);
+
+            // act
+            IModMetadata[] mods = new ModResolver().ReadManifests(rootFolder, new JsonHelper(), new ModCompatibility[0], new DisabledMod[0]).ToArray();
+            IModMetadata mod = mods.FirstOrDefault();
+
+            // assert
+            Assert.AreEqual(1, mods.Length, 0, $"Expected to find one manifest, found {mods.Length} instead.");
+            Assert.AreEqual(ModMetadataStatus.Failed, mod.Status, "The mod metadata was not marked failed.");
+            Assert.IsNotNull(mod.Error, "The mod metadata did not have an error message set.");
+        }
+
+        [Test(Description = "Assert that the resolver correctly reads manifest data from a randomised file.")]
+        public void ReadBasicManifest_CanReadFile()
+        {
+            // create manifest data
+            IDictionary<string, object> originalDependency = new Dictionary<string, object>
+            {
+                [nameof(IManifestDependency.UniqueID)] = Sample.String()
+            };
+            IDictionary<string, object> original = new Dictionary<string, object>
+            {
+                [nameof(IManifest.Name)] = Sample.String(),
+                [nameof(IManifest.Author)] = Sample.String(),
+                [nameof(IManifest.Version)] = new SemanticVersion(Sample.Int(), Sample.Int(), Sample.Int(), Sample.String()),
+                [nameof(IManifest.Description)] = Sample.String(),
+                [nameof(IManifest.UniqueID)] = $"{Sample.String()}.{Sample.String()}",
+                [nameof(IManifest.EntryDll)] = $"{Sample.String()}.dll",
+                [nameof(IManifest.MinimumApiVersion)] = $"{Sample.Int()}.{Sample.Int()}-{Sample.String()}",
+                [nameof(IManifest.Dependencies)] = new[] { originalDependency },
+                ["ExtraString"] = Sample.String(),
+                ["ExtraInt"] = Sample.Int()
+            };
+
+            // write to filesystem
+            string rootFolder = Path.Combine(Path.GetTempPath(), Guid.NewGuid().ToString("N"));
+            string modFolder = Path.Combine(rootFolder, Guid.NewGuid().ToString("N"));
+            string filename = Path.Combine(modFolder, "manifest.json");
+            Directory.CreateDirectory(modFolder);
+            File.WriteAllText(filename, JsonConvert.SerializeObject(original));
+
+            // act
+            IModMetadata[] mods = new ModResolver().ReadManifests(rootFolder, new JsonHelper(), new ModCompatibility[0], new DisabledMod[0]).ToArray();
+            IModMetadata mod = mods.FirstOrDefault();
+
+            // assert
+            Assert.AreEqual(1, mods.Length, 0, "Expected to find one manifest.");
+            Assert.IsNotNull(mod, "The loaded manifest shouldn't be null.");
+            Assert.AreEqual(null, mod.Compatibility, "The compatibility record should be null since we didn't provide one.");
+            Assert.AreEqual(modFolder, mod.DirectoryPath, "The directory path doesn't match.");
+            Assert.AreEqual(ModMetadataStatus.Found, mod.Status, "The status doesn't match.");
+            Assert.AreEqual(null, mod.Error, "The error should be null since parsing should have succeeded.");
+
+            Assert.AreEqual(original[nameof(IManifest.Name)], mod.DisplayName, "The display name should use the manifest name.");
+            Assert.AreEqual(original[nameof(IManifest.Name)], mod.Manifest.Name, "The manifest's name doesn't match.");
+            Assert.AreEqual(original[nameof(IManifest.Author)], mod.Manifest.Author, "The manifest's author doesn't match.");
+            Assert.AreEqual(original[nameof(IManifest.Description)], mod.Manifest.Description, "The manifest's description doesn't match.");
+            Assert.AreEqual(original[nameof(IManifest.EntryDll)], mod.Manifest.EntryDll, "The manifest's entry DLL doesn't match.");
+            Assert.AreEqual(original[nameof(IManifest.MinimumApiVersion)], mod.Manifest.MinimumApiVersion, "The manifest's minimum API version doesn't match.");
+            Assert.AreEqual(original[nameof(IManifest.Version)]?.ToString(), mod.Manifest.Version?.ToString(), "The manifest's version doesn't match.");
+
+            Assert.IsNotNull(mod.Manifest.ExtraFields, "The extra fields should not be null.");
+            Assert.AreEqual(2, mod.Manifest.ExtraFields.Count, "The extra fields should contain two values.");
+            Assert.AreEqual(original["ExtraString"], mod.Manifest.ExtraFields["ExtraString"], "The manifest's extra fields should contain an 'ExtraString' value.");
+            Assert.AreEqual(original["ExtraInt"], mod.Manifest.ExtraFields["ExtraInt"], "The manifest's extra fields should contain an 'ExtraInt' value.");
+
+            Assert.IsNotNull(mod.Manifest.Dependencies, "The dependencies field should not be null.");
+            Assert.AreEqual(1, mod.Manifest.Dependencies.Length, "The dependencies field should contain one value.");
+            Assert.AreEqual(originalDependency[nameof(IManifestDependency.UniqueID)], mod.Manifest.Dependencies[0].UniqueID, "The first dependency's unique ID doesn't match.");
+        }
+
+        /****
+        ** ValidateManifests
+        ****/
+        [Test(Description = "Assert that validation doesn't fail if there are no mods installed.")]
+        public void ValidateManifests_NoMods_DoesNothing()
+        {
+            new ModResolver().ValidateManifests(new ModMetadata[0], apiVersion: new SemanticVersion("1.0"));
+        }
+
+        [Test(Description = "Assert that validation skips manifests that have already failed without calling any other properties.")]
+        public void ValidateManifests_Skips_Failed()
+        {
+            // arrange
+            Mock<IModMetadata> mock = new Mock<IModMetadata>(MockBehavior.Strict);
+            mock.Setup(p => p.Status).Returns(ModMetadataStatus.Failed);
+
+            // act
+            new ModResolver().ValidateManifests(new[] { mock.Object }, apiVersion: new SemanticVersion("1.0"));
+
+            // assert
+            mock.VerifyGet(p => p.Status, Times.Once, "The validation did not check the manifest status.");
+        }
+
+        [Test(Description = "Assert that validation fails if the mod has 'assume broken' compatibility.")]
+        public void ValidateManifests_ModCompatibility_AssumeBroken_Fails()
+        {
+            // arrange
+            Mock<IModMetadata> mock = new Mock<IModMetadata>(MockBehavior.Strict);
+            mock.Setup(p => p.Status).Returns(ModMetadataStatus.Found);
+            mock.Setup(p => p.Compatibility).Returns(new ModCompatibility { Compatibility = ModCompatibilityType.AssumeBroken });
+            mock.Setup(p => p.SetStatus(ModMetadataStatus.Failed, It.IsAny<string>())).Returns(() => mock.Object);
+
+            // act
+            new ModResolver().ValidateManifests(new[] { mock.Object }, apiVersion: new SemanticVersion("1.0"));
+
+            // assert
+            mock.Verify(p => p.SetStatus(ModMetadataStatus.Failed, It.IsAny<string>()), Times.Once, "The validation did not fail the metadata.");
+        }
+
+        [Test(Description = "Assert that validation fails when the minimum API version is higher than the current SMAPI version.")]
+        public void ValidateManifests_MinimumApiVersion_Fails()
+        {
+            // arrange
+            Mock<IModMetadata> mock = new Mock<IModMetadata>(MockBehavior.Strict);
+            mock.Setup(p => p.Status).Returns(ModMetadataStatus.Found);
+            mock.Setup(p => p.Compatibility).Returns(() => null);
+            mock.Setup(p => p.Manifest).Returns(this.GetManifest(m => m.MinimumApiVersion = "1.1"));
+            mock.Setup(p => p.SetStatus(ModMetadataStatus.Failed, It.IsAny<string>())).Returns(() => mock.Object);
+
+            // act
+            new ModResolver().ValidateManifests(new[] { mock.Object }, apiVersion: new SemanticVersion("1.0"));
+
+            // assert
+            mock.Verify(p => p.SetStatus(ModMetadataStatus.Failed, It.IsAny<string>()), Times.Once, "The validation did not fail the metadata.");
+        }
+
+        [Test(Description = "Assert that validation fails when the manifest references a DLL that does not exist.")]
+        public void ValidateManifests_MissingEntryDLL_Fails()
+        {
+            // arrange
+            Mock<IModMetadata> mock = new Mock<IModMetadata>(MockBehavior.Strict);
+            mock.Setup(p => p.Status).Returns(ModMetadataStatus.Found);
+            mock.Setup(p => p.Compatibility).Returns(() => null);
+            mock.Setup(p => p.Manifest).Returns(this.GetManifest());
+            mock.Setup(p => p.DirectoryPath).Returns(Path.GetTempPath());
+            mock.Setup(p => p.SetStatus(ModMetadataStatus.Failed, It.IsAny<string>())).Returns(() => mock.Object);
+
+            // act
+            new ModResolver().ValidateManifests(new[] { mock.Object }, apiVersion: new SemanticVersion("1.0"));
+
+            // assert
+            mock.Verify(p => p.SetStatus(ModMetadataStatus.Failed, It.IsAny<string>()), Times.Once, "The validation did not fail the metadata.");
+        }
+
+        [Test(Description = "Assert that validation fails when the manifest references a DLL that does not exist.")]
+        public void ValidateManifests_Valid_Passes()
+        {
+            // set up manifest
+            IManifest manifest = this.GetManifest();
+
+            // create DLL
+            string modFolder = Path.Combine(Path.GetTempPath(), Guid.NewGuid().ToString("N"));
+            Directory.CreateDirectory(modFolder);
+            File.WriteAllText(Path.Combine(modFolder, manifest.EntryDll), "");
+
+            // arrange
+            Mock<IModMetadata> mock = new Mock<IModMetadata>(MockBehavior.Strict);
+            mock.Setup(p => p.Status).Returns(ModMetadataStatus.Found);
+            mock.Setup(p => p.Compatibility).Returns(() => null);
+            mock.Setup(p => p.Manifest).Returns(manifest);
+            mock.Setup(p => p.DirectoryPath).Returns(modFolder);
+
+            // act
+            new ModResolver().ValidateManifests(new[] { mock.Object }, apiVersion: new SemanticVersion("1.0"));
+
+            // assert
+            // if Moq doesn't throw a method-not-setup exception, the validation didn't override the status.
+        }
+
+        /****
+        ** ProcessDependencies
+        ****/
+        [Test(Description = "Assert that processing dependencies doesn't fail if there are no mods installed.")]
+        public void ProcessDependencies_NoMods_DoesNothing()
+        {
+            // act
+            IModMetadata[] mods = new ModResolver().ProcessDependencies(new IModMetadata[0]).ToArray();
+
+            // assert
+            Assert.AreEqual(0, mods.Length, 0, "Expected to get an empty list of mods.");
+        }
+
+        [Test(Description = "Assert that processing dependencies doesn't change the order if there are no mod dependencies.")]
+        public void ProcessDependencies_NoDependencies_DoesNothing()
+        {
+            // arrange
+            // A B C
+            Mock<IModMetadata> modA = this.GetMetadata("Mod A");
+            Mock<IModMetadata> modB = this.GetMetadata("Mod B");
+            Mock<IModMetadata> modC = this.GetMetadata("Mod C");
+
+            // act
+            IModMetadata[] mods = new ModResolver().ProcessDependencies(new[] { modA.Object, modB.Object, modC.Object }).ToArray();
+
+            // assert
+            Assert.AreEqual(3, mods.Length, 0, "Expected to get the same number of mods input.");
+            Assert.AreSame(modA.Object, mods[0], "The load order unexpectedly changed with no dependencies.");
+            Assert.AreSame(modB.Object, mods[1], "The load order unexpectedly changed with no dependencies.");
+            Assert.AreSame(modC.Object, mods[2], "The load order unexpectedly changed with no dependencies.");
+        }
+
+        [Test(Description = "Assert that processing dependencies skips mods that have already failed without calling any other properties.")]
+        public void ProcessDependencies_Skips_Failed()
+        {
+            // arrange
+            Mock<IModMetadata> mock = new Mock<IModMetadata>(MockBehavior.Strict);
+            mock.Setup(p => p.Status).Returns(ModMetadataStatus.Failed);
+
+            // act
+            new ModResolver().ProcessDependencies(new[] { mock.Object });
+
+            // assert
+            mock.VerifyGet(p => p.Status, Times.Once, "The validation did not check the manifest status.");
+        }
+
+        [Test(Description = "Assert that simple dependencies are reordered correctly.")]
+        public void ProcessDependencies_Reorders_SimpleDependencies()
+        {
+            // arrange
+            // A ◀── B
+            // ▲     ▲
+            // │     │
+            // └─ C ─┘
+            Mock<IModMetadata> modA = this.GetMetadata("Mod A");
+            Mock<IModMetadata> modB = this.GetMetadata("Mod B", dependencies: new[] { "Mod A" });
+            Mock<IModMetadata> modC = this.GetMetadata("Mod C", dependencies: new[] { "Mod A", "Mod B" });
+
+            // act
+            IModMetadata[] mods = new ModResolver().ProcessDependencies(new[] { modC.Object, modA.Object, modB.Object }).ToArray();
+
+            // assert
+            Assert.AreEqual(3, mods.Length, 0, "Expected to get the same number of mods input.");
+            Assert.AreSame(modA.Object, mods[0], "The load order is incorrect: mod A should be first since the other mods depend on it.");
+            Assert.AreSame(modB.Object, mods[1], "The load order is incorrect: mod B should be second since it needs mod A, and is needed by mod C.");
+            Assert.AreSame(modC.Object, mods[2], "The load order is incorrect: mod C should be third since it needs both mod A and mod B.");
+        }
+
+        [Test(Description = "Assert that simple dependency chains are reordered correctly.")]
+        public void ProcessDependencies_Reorders_DependencyChain()
+        {
+            // arrange
+            // A ◀── B ◀── C ◀── D
+            Mock<IModMetadata> modA = this.GetMetadata("Mod A");
+            Mock<IModMetadata> modB = this.GetMetadata("Mod B", dependencies: new[] { "Mod A" });
+            Mock<IModMetadata> modC = this.GetMetadata("Mod C", dependencies: new[] { "Mod B" });
+            Mock<IModMetadata> modD = this.GetMetadata("Mod D", dependencies: new[] { "Mod C" });
+
+            // act
+            IModMetadata[] mods = new ModResolver().ProcessDependencies(new[] { modC.Object, modA.Object, modB.Object, modD.Object }).ToArray();
+
+            // assert
+            Assert.AreEqual(4, mods.Length, 0, "Expected to get the same number of mods input.");
+            Assert.AreSame(modA.Object, mods[0], "The load order is incorrect: mod A should be first since it's needed by mod B.");
+            Assert.AreSame(modB.Object, mods[1], "The load order is incorrect: mod B should be second since it needs mod A, and is needed by mod C.");
+            Assert.AreSame(modC.Object, mods[2], "The load order is incorrect: mod C should be third since it needs mod B, and is needed by mod D.");
+            Assert.AreSame(modD.Object, mods[3], "The load order is incorrect: mod D should be fourth since it needs mod C.");
+        }
+
+        [Test(Description = "Assert that overlapping dependency chains are reordered correctly.")]
+        public void ProcessDependencies_Reorders_OverlappingDependencyChain()
+        {
+            // arrange
+            // A ◀── B ◀── C ◀── D
+            //       ▲     ▲
+            //       │     │
+            //       E ◀── F
+            Mock<IModMetadata> modA = this.GetMetadata("Mod A");
+            Mock<IModMetadata> modB = this.GetMetadata("Mod B", dependencies: new[] { "Mod A" });
+            Mock<IModMetadata> modC = this.GetMetadata("Mod C", dependencies: new[] { "Mod B" });
+            Mock<IModMetadata> modD = this.GetMetadata("Mod D", dependencies: new[] { "Mod C" });
+            Mock<IModMetadata> modE = this.GetMetadata("Mod E", dependencies: new[] { "Mod B" });
+            Mock<IModMetadata> modF = this.GetMetadata("Mod F", dependencies: new[] { "Mod C", "Mod E" });
+
+            // act
+            IModMetadata[] mods = new ModResolver().ProcessDependencies(new[] { modC.Object, modA.Object, modB.Object, modD.Object, modF.Object, modE.Object }).ToArray();
+
+            // assert
+            Assert.AreEqual(6, mods.Length, 0, "Expected to get the same number of mods input.");
+            Assert.AreSame(modA.Object, mods[0], "The load order is incorrect: mod A should be first since it's needed by mod B.");
+            Assert.AreSame(modB.Object, mods[1], "The load order is incorrect: mod B should be second since it needs mod A, and is needed by mod C.");
+            Assert.AreSame(modC.Object, mods[2], "The load order is incorrect: mod C should be third since it needs mod B, and is needed by mod D.");
+            Assert.AreSame(modD.Object, mods[3], "The load order is incorrect: mod D should be fourth since it needs mod C.");
+            Assert.AreSame(modE.Object, mods[4], "The load order is incorrect: mod E should be fifth since it needs mod B, but is specified after C which also needs mod B.");
+            Assert.AreSame(modF.Object, mods[5], "The load order is incorrect: mod F should be last since it needs mods E and C.");
+        }
+
+        [Test(Description = "Assert that mods with circular dependency chains are skipped, but any other mods are loaded in the correct order.")]
+        public void ProcessDependencies_Skips_CircularDependentMods()
+        {
+            // arrange
+            // A ◀── B ◀── C ──▶ D
+            //             ▲     │
+            //             │     ▼
+            //             └──── E
+            Mock<IModMetadata> modA = this.GetMetadata("Mod A");
+            Mock<IModMetadata> modB = this.GetMetadata("Mod B", dependencies: new[] { "Mod A" });
+            Mock<IModMetadata> modC = this.GetMetadata("Mod C", dependencies: new[] { "Mod B", "Mod D" }, allowStatusChange: true);
+            Mock<IModMetadata> modD = this.GetMetadata("Mod D", dependencies: new[] { "Mod E" }, allowStatusChange: true);
+            Mock<IModMetadata> modE = this.GetMetadata("Mod E", dependencies: new[] { "Mod C" }, allowStatusChange: true);
+
+            // act
+            IModMetadata[] mods = new ModResolver().ProcessDependencies(new[] { modC.Object, modA.Object, modB.Object, modD.Object, modE.Object }).ToArray();
+
+            // assert
+            Assert.AreEqual(5, mods.Length, 0, "Expected to get the same number of mods input.");
+            Assert.AreSame(modA.Object, mods[0], "The load order is incorrect: mod A should be first since it's needed by mod B.");
+            Assert.AreSame(modB.Object, mods[1], "The load order is incorrect: mod B should be second since it needs mod A.");
+            modC.Verify(p => p.SetStatus(ModMetadataStatus.Failed, It.IsAny<string>()), Times.Once, "Mod C was expected to fail since it's part of a dependency loop.");
+            modD.Verify(p => p.SetStatus(ModMetadataStatus.Failed, It.IsAny<string>()), Times.Once, "Mod D was expected to fail since it's part of a dependency loop.");
+            modE.Verify(p => p.SetStatus(ModMetadataStatus.Failed, It.IsAny<string>()), Times.Once, "Mod E was expected to fail since it's part of a dependency loop.");
+        }
+
+        [Test(Description = "Assert that dependencies are sorted correctly even if some of the mods failed during metadata loading.")]
+        public void ProcessDependencies_WithSomeFailedMods_Succeeds()
+        {
+            // arrange
+            // A ◀── B ◀── C   D (failed)
+            Mock<IModMetadata> modA = this.GetMetadata("Mod A");
+            Mock<IModMetadata> modB = this.GetMetadata("Mod B", dependencies: new[] { "Mod A" });
+            Mock<IModMetadata> modC = this.GetMetadata("Mod C", dependencies: new[] { "Mod B" }, allowStatusChange: true);
+            Mock<IModMetadata> modD = new Mock<IModMetadata>(MockBehavior.Strict);
+            modD.Setup(p => p.Manifest).Returns<IManifest>(null);
+            modD.Setup(p => p.Status).Returns(ModMetadataStatus.Failed);
+
+            // act
+            IModMetadata[] mods = new ModResolver().ProcessDependencies(new[] { modC.Object, modA.Object, modB.Object, modD.Object }).ToArray();
+
+            // assert
+            Assert.AreEqual(4, mods.Length, 0, "Expected to get the same number of mods input.");
+            Assert.AreSame(modD.Object, mods[0], "The load order is incorrect: mod D should be first since it was already failed.");
+            Assert.AreSame(modA.Object, mods[1], "The load order is incorrect: mod A should be second since it's needed by mod B.");
+            Assert.AreSame(modB.Object, mods[2], "The load order is incorrect: mod B should be third since it needs mod A, and is needed by mod C.");
+            Assert.AreSame(modC.Object, mods[3], "The load order is incorrect: mod C should be fourth since it needs mod B, and is needed by mod D.");
+        }
+
+        [Test(Description = "Assert that dependencies are failed if they don't meet the minimum version.")]
+        public void ProcessDependencies_WithMinVersions_FailsIfNotMet()
+        {
+            // arrange
+            // A 1.0 ◀── B (need A 1.1)
+            Mock<IModMetadata> modA = this.GetMetadata(this.GetManifest("Mod A", "1.0"));
+            Mock<IModMetadata> modB = this.GetMetadata(this.GetManifest("Mod B", "1.0", new ManifestDependency("Mod A", "1.1")), allowStatusChange: true);
+
+            // act
+            IModMetadata[] mods = new ModResolver().ProcessDependencies(new[] { modA.Object, modB.Object }).ToArray();
+
+            // assert
+            Assert.AreEqual(2, mods.Length, 0, "Expected to get the same number of mods input.");
+            modB.Verify(p => p.SetStatus(ModMetadataStatus.Failed, It.IsAny<string>()), Times.Once, "Mod B unexpectedly didn't fail even though it needs a newer version of Mod A.");
+        }
+
+        [Test(Description = "Assert that dependencies are accepted if they meet the minimum version.")]
+        public void ProcessDependencies_WithMinVersions_SucceedsIfMet()
+        {
+            // arrange
+            // A 1.0 ◀── B (need A 1.0-beta)
+            Mock<IModMetadata> modA = this.GetMetadata(this.GetManifest("Mod A", "1.0"));
+            Mock<IModMetadata> modB = this.GetMetadata(this.GetManifest("Mod B", "1.0", new ManifestDependency("Mod A", "1.0-beta")), allowStatusChange: false);
+
+            // act
+            IModMetadata[] mods = new ModResolver().ProcessDependencies(new[] { modA.Object, modB.Object }).ToArray();
+
+            // assert
+            Assert.AreEqual(2, mods.Length, 0, "Expected to get the same number of mods input.");
+            Assert.AreSame(modA.Object, mods[0], "The load order is incorrect: mod A should be first since it's needed by mod B.");
+            Assert.AreSame(modB.Object, mods[1], "The load order is incorrect: mod B should be second since it needs mod A.");
+        }
+
+
+        /*********
+        ** Private methods
+        *********/
+        /// <summary>Get a randomised basic manifest.</summary>
+        /// <param name="adjust">Adjust the generated manifest.</param>
+        private Manifest GetManifest(Action<Manifest> adjust = null)
+        {
+            Manifest manifest = new Manifest
+            {
+                Name = Sample.String(),
+                Author = Sample.String(),
+                Version = new SemanticVersion(Sample.Int(), Sample.Int(), Sample.Int(), Sample.String()),
+                Description = Sample.String(),
+                UniqueID = $"{Sample.String()}.{Sample.String()}",
+                EntryDll = $"{Sample.String()}.dll"
+            };
+            adjust?.Invoke(manifest);
+            return manifest;
+        }
+
+        /// <summary>Get a randomised basic manifest.</summary>
+        /// <param name="uniqueID">The mod's name and unique ID.</param>
+        /// <param name="version">The mod version.</param>
+        /// <param name="dependencies">The dependencies this mod requires.</param>
+        private IManifest GetManifest(string uniqueID, string version, params IManifestDependency[] dependencies)
+        {
+            return this.GetManifest(manifest =>
+            {
+                manifest.Name = uniqueID;
+                manifest.UniqueID = uniqueID;
+                manifest.Version = new SemanticVersion(version);
+                manifest.Dependencies = dependencies;
+            });
+        }
+
+        /// <summary>Get a randomised basic manifest.</summary>
+        /// <param name="uniqueID">The mod's name and unique ID.</param>
+        private Mock<IModMetadata> GetMetadata(string uniqueID)
+        {
+            return this.GetMetadata(this.GetManifest(uniqueID, "1.0"));
+        }
+
+        /// <summary>Get a randomised basic manifest.</summary>
+        /// <param name="uniqueID">The mod's name and unique ID.</param>
+        /// <param name="dependencies">The dependencies this mod requires.</param>
+        /// <param name="allowStatusChange">Whether the code being tested is allowed to change the mod status.</param>
+        private Mock<IModMetadata> GetMetadata(string uniqueID, string[] dependencies, bool allowStatusChange = false)
+        {
+            IManifest manifest = this.GetManifest(uniqueID, "1.0", dependencies?.Select(dependencyID => (IManifestDependency)new ManifestDependency(dependencyID, null)).ToArray());
+            return this.GetMetadata(manifest, allowStatusChange);
+        }
+
+        /// <summary>Get a randomised basic manifest.</summary>
+        /// <param name="manifest">The mod manifest.</param>
+        /// <param name="allowStatusChange">Whether the code being tested is allowed to change the mod status.</param>
+        private Mock<IModMetadata> GetMetadata(IManifest manifest, bool allowStatusChange = false)
+        {
+            Mock<IModMetadata> mod = new Mock<IModMetadata>(MockBehavior.Strict);
+            mod.Setup(p => p.Status).Returns(ModMetadataStatus.Found);
+            mod.Setup(p => p.DisplayName).Returns(manifest.UniqueID);
+            mod.Setup(p => p.Manifest).Returns(manifest);
+            if (allowStatusChange)
+            {
+                mod
+                    .Setup(p => p.SetStatus(It.IsAny<ModMetadataStatus>(), It.IsAny<string>()))
+                    .Callback<ModMetadataStatus, string>((status, message) => Console.WriteLine($"<{manifest.UniqueID} changed status: [{status}] {message}"))
+                    .Returns(mod.Object);
+            }
+            return mod;
+        }
+    }
+}
diff --git a/src/StardewModdingAPI.Tests/Core/TranslationTests.cs b/src/StardewModdingAPI.Tests/Core/TranslationTests.cs
new file mode 100644
index 00000000..ce3431e4
--- /dev/null
+++ b/src/StardewModdingAPI.Tests/Core/TranslationTests.cs
@@ -0,0 +1,356 @@
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using NUnit.Framework;
+using StardewModdingAPI.Framework;
+using StardewValley;
+
+namespace StardewModdingAPI.Tests.Core
+{
+    /// <summary>Unit tests for <see cref="TranslationHelper"/> and <see cref="Translation"/>.</summary>
+    [TestFixture]
+    public class TranslationTests
+    {
+        /*********
+        ** Data
+        *********/
+        /// <summary>Sample translation text for unit tests.</summary>
+        public static string[] Samples = { null, "", "  ", "boop", "  boop  " };
+
+
+        /*********
+        ** Unit tests
+        *********/
+        /****
+        ** Translation helper
+        ****/
+        [Test(Description = "Assert that the translation helper correctly handles no translations.")]
+        public void Helper_HandlesNoTranslations()
+        {
+            // arrange
+            var data = new Dictionary<string, IDictionary<string, string>>();
+
+            // act
+            ITranslationHelper helper = new TranslationHelper("ModName", "en", LocalizedContentManager.LanguageCode.en).SetTranslations(data);
+            Translation translation = helper.Get("key");
+            Translation[] translationList = helper.GetTranslations()?.ToArray();
+
+            // assert
+            Assert.AreEqual("en", helper.Locale, "The locale doesn't match the input value.");
+            Assert.AreEqual(LocalizedContentManager.LanguageCode.en, helper.LocaleEnum, "The locale enum doesn't match the input value.");
+            Assert.IsNotNull(translationList, "The full list of translations is unexpectedly null.");
+            Assert.AreEqual(0, translationList.Length, "The full list of translations is unexpectedly not empty.");
+
+            Assert.IsNotNull(translation, "The translation helper unexpectedly returned a null translation.");
+            Assert.AreEqual(this.GetPlaceholderText("key"), translation.ToString(), "The translation returned an unexpected value.");
+        }
+
+        [Test(Description = "Assert that the translation helper returns the expected translations correctly.")]
+        public void Helper_GetTranslations_ReturnsExpectedText()
+        {
+            // arrange
+            var data = this.GetSampleData();
+            var expected = this.GetExpectedTranslations();
+
+            // act
+            var actual = new Dictionary<string, Translation[]>();
+            TranslationHelper helper = new TranslationHelper("ModName", "en", LocalizedContentManager.LanguageCode.en).SetTranslations(data);
+            foreach (string locale in expected.Keys)
+            {
+                this.AssertSetLocale(helper, locale, LocalizedContentManager.LanguageCode.en);
+                actual[locale] = helper.GetTranslations()?.ToArray();
+            }
+
+            // assert
+            foreach (string locale in expected.Keys)
+            {
+                Assert.IsNotNull(actual[locale], $"The translations for {locale} is unexpectedly null.");
+                Assert.That(actual[locale], Is.EquivalentTo(expected[locale]).Using<Translation, Translation>(this.CompareEquality), $"The translations for {locale} don't match the expected values.");
+            }
+        }
+
+        [Test(Description = "Assert that the translations returned by the helper has the expected text.")]
+        public void Helper_Get_ReturnsExpectedText()
+        {
+            // arrange
+            var data = this.GetSampleData();
+            var expected = this.GetExpectedTranslations();
+
+            // act
+            var actual = new Dictionary<string, Translation[]>();
+            TranslationHelper helper = new TranslationHelper("ModName", "en", LocalizedContentManager.LanguageCode.en).SetTranslations(data);
+            foreach (string locale in expected.Keys)
+            {
+                this.AssertSetLocale(helper, locale, LocalizedContentManager.LanguageCode.en);
+
+                List<Translation> translations = new List<Translation>();
+                foreach (Translation translation in expected[locale])
+                    translations.Add(helper.Get(translation.Key));
+                actual[locale] = translations.ToArray();
+            }
+
+            // assert
+            foreach (string locale in expected.Keys)
+            {
+                Assert.IsNotNull(actual[locale], $"The translations for {locale} is unexpectedly null.");
+                Assert.That(actual[locale], Is.EquivalentTo(expected[locale]).Using<Translation, Translation>(this.CompareEquality), $"The translations for {locale} don't match the expected values.");
+            }
+        }
+
+        /****
+        ** Translation
+        ****/
+        [Test(Description = "Assert that HasValue returns the expected result for various inputs.")]
+        [TestCase(null, ExpectedResult = false)]
+        [TestCase("", ExpectedResult = false)]
+        [TestCase("  ", ExpectedResult = true)]
+        [TestCase("boop", ExpectedResult = true)]
+        [TestCase("  boop  ", ExpectedResult = true)]
+        public bool Translation_HasValue(string text)
+        {
+            return new Translation("ModName", "pt-BR", "key", text).HasValue();
+        }
+
+        [Test(Description = "Assert that the translation's ToString method returns the expected text for various inputs.")]
+        public void Translation_ToString([ValueSource(nameof(TranslationTests.Samples))] string text)
+        {
+            // act
+            Translation translation = new Translation("ModName", "pt-BR", "key", text);
+
+            // assert
+            if (translation.HasValue())
+                Assert.AreEqual(text, translation.ToString(), "The translation returned an unexpected value given a valid input.");
+            else
+                Assert.AreEqual(this.GetPlaceholderText("key"), translation.ToString(), "The translation returned an unexpected value given a null or empty input.");
+        }
+
+        [Test(Description = "Assert that the translation's implicit string conversion returns the expected text for various inputs.")]
+        public void Translation_ImplicitStringConversion([ValueSource(nameof(TranslationTests.Samples))] string text)
+        {
+            // act
+            Translation translation = new Translation("ModName", "pt-BR", "key", text);
+
+            // assert
+            if (translation.HasValue())
+                Assert.AreEqual(text, (string)translation, "The translation returned an unexpected value given a valid input.");
+            else
+                Assert.AreEqual(this.GetPlaceholderText("key"), (string)translation, "The translation returned an unexpected value given a null or empty input.");
+        }
+
+        [Test(Description = "Assert that the translation returns the expected text given a use-placeholder setting.")]
+        public void Translation_UsePlaceholder([Values(true, false)] bool value, [ValueSource(nameof(TranslationTests.Samples))] string text)
+        {
+            // act
+            Translation translation = new Translation("ModName", "pt-BR", "key", text).UsePlaceholder(value);
+
+            // assert
+            if (translation.HasValue())
+                Assert.AreEqual(text, translation.ToString(), "The translation returned an unexpected value given a valid input.");
+            else if (!value)
+                Assert.AreEqual(text, translation.ToString(), "The translation returned an unexpected value given a null or empty input with the placeholder disabled.");
+            else
+                Assert.AreEqual(this.GetPlaceholderText("key"), translation.ToString(), "The translation returned an unexpected value given a null or empty input with the placeholder enabled.");
+        }
+
+        [Test(Description = "Assert that the translation's Assert method throws the expected exception.")]
+        public void Translation_Assert([ValueSource(nameof(TranslationTests.Samples))] string text)
+        {
+            // act
+            Translation translation = new Translation("ModName", "pt-BR", "key", text);
+
+            // assert
+            if (translation.HasValue())
+                Assert.That(() => translation.Assert(), Throws.Nothing, "The assert unexpected threw an exception for a valid input.");
+            else
+                Assert.That(() => translation.Assert(), Throws.Exception.TypeOf<KeyNotFoundException>(), "The assert didn't throw an exception for invalid input.");
+        }
+
+        [Test(Description = "Assert that the translation returns the expected text after setting the default.")]
+        public void Translation_Default([ValueSource(nameof(TranslationTests.Samples))] string text, [ValueSource(nameof(TranslationTests.Samples))] string @default)
+        {
+            // act
+            Translation translation = new Translation("ModName", "pt-BR", "key", text).Default(@default);
+
+            // assert
+            if (!string.IsNullOrEmpty(text))
+                Assert.AreEqual(text, translation.ToString(), "The translation returned an unexpected value given a valid base text.");
+            else if (!string.IsNullOrEmpty(@default))
+                Assert.AreEqual(@default, translation.ToString(), "The translation returned an unexpected value given a null or empty base text, but valid default.");
+            else
+                Assert.AreEqual(this.GetPlaceholderText("key"), translation.ToString(), "The translation returned an unexpected value given a null or empty base and default text.");
+        }
+
+        /****
+        ** Translation tokens
+        ****/
+        [Test(Description = "Assert that multiple translation tokens are replaced correctly regardless of the token structure.")]
+        public void Translation_Tokens([Values("anonymous object", "class", "IDictionary<string, object>", "IDictionary<string, string>")] string structure)
+        {
+            // arrange
+            string start = Guid.NewGuid().ToString("N");
+            string middle = Guid.NewGuid().ToString("N");
+            string end = Guid.NewGuid().ToString("N");
+            const string input = "{{start}} tokens are properly replaced (including {{middle}} {{  MIDdlE}}) {{end}}";
+            string expected = $"{start} tokens are properly replaced (including {middle} {middle}) {end}";
+
+            // act
+            Translation translation = new Translation("ModName", "pt-BR", "key", input);
+            switch (structure)
+            {
+                case "anonymous object":
+                    translation = translation.Tokens(new { start, middle, end });
+                    break;
+
+                case "class":
+                    translation = translation.Tokens(new TokenModel { Start = start, Middle = middle, End = end });
+                    break;
+
+                case "IDictionary<string, object>":
+                    translation = translation.Tokens(new Dictionary<string, object> { ["start"] = start, ["middle"] = middle, ["end"] = end });
+                    break;
+
+                case "IDictionary<string, string>":
+                    translation = translation.Tokens(new Dictionary<string, string> { ["start"] = start, ["middle"] = middle, ["end"] = end });
+                    break;
+
+                default:
+                    throw new NotSupportedException($"Unknown structure '{structure}'.");
+            }
+
+            // assert
+            Assert.AreEqual(expected, translation.ToString(), "The translation returned an unexpected text.");
+        }
+
+        [Test(Description = "Assert that the translation can replace tokens in all valid formats.")]
+        [TestCase("{{value}}", "value")]
+        [TestCase("{{ value }}", "value")]
+        [TestCase("{{value       }}", "value")]
+        [TestCase("{{ the_value }}", "the_value")]
+        [TestCase("{{ the.value_here }}", "the.value_here")]
+        [TestCase("{{ the_value-here.... }}", "the_value-here....")]
+        [TestCase("{{ tHe_vALuE-HEre.... }}", "tHe_vALuE-HEre....")]
+        public void Translation_Tokens_ValidFormats(string text, string key)
+        {
+            // arrange
+            string value = Guid.NewGuid().ToString("N");
+
+            // act
+            Translation translation = new Translation("ModName", "pt-BR", "key", text).Tokens(new Dictionary<string, object> { [key] = value });
+
+            // assert
+            Assert.AreEqual(value, translation.ToString(), "The translation returned an unexpected value given a valid base text.");
+        }
+
+        [Test(Description = "Assert that translation tokens are case-insensitive and surrounding-whitespace-insensitive.")]
+        [TestCase("{{value}}", "value")]
+        [TestCase("{{VaLuE}}", "vAlUe")]
+        [TestCase("{{VaLuE   }}", "   vAlUe")]
+        public void Translation_Tokens_KeysAreNormalised(string text, string key)
+        {
+            // arrange
+            string value = Guid.NewGuid().ToString("N");
+
+            // act
+            Translation translation = new Translation("ModName", "pt-BR", "key", text).Tokens(new Dictionary<string, object> { [key] = value });
+
+            // assert
+            Assert.AreEqual(value, translation.ToString(), "The translation returned an unexpected value given a valid base text.");
+        }
+
+
+        /*********
+        ** Private methods
+        *********/
+        /// <summary>Set a translation helper's locale and assert that it was set correctly.</summary>
+        /// <param name="helper">The translation helper to change.</param>
+        /// <param name="locale">The expected locale.</param>
+        /// <param name="localeEnum">The expected game language code.</param>
+        private void AssertSetLocale(TranslationHelper helper, string locale, LocalizedContentManager.LanguageCode localeEnum)
+        {
+            helper.SetLocale(locale, localeEnum);
+            Assert.AreEqual(locale, helper.Locale, "The locale doesn't match the input value.");
+            Assert.AreEqual(localeEnum, helper.LocaleEnum, "The locale enum doesn't match the input value.");
+        }
+
+        /// <summary>Get sample raw translations to input.</summary>
+        private IDictionary<string, IDictionary<string, string>> GetSampleData()
+        {
+            return new Dictionary<string, IDictionary<string, string>>
+            {
+                ["default"] = new Dictionary<string, string>
+                {
+                    ["key A"] = "default A",
+                    ["key C"] = "default C"
+                },
+                ["en"] = new Dictionary<string, string>
+                {
+                    ["key A"] = "en A",
+                    ["key B"] = "en B"
+                },
+                ["en-US"] = new Dictionary<string, string>(),
+                ["zzz"] = new Dictionary<string, string>
+                {
+                    ["key A"] = "zzz A"
+                }
+            };
+        }
+
+        /// <summary>Get the expected translation output given <see cref="TranslationTests.GetSampleData"/>, based on the expected locale fallback.</summary>
+        private IDictionary<string, Translation[]> GetExpectedTranslations()
+        {
+            var expected = new Dictionary<string, Translation[]>
+            {
+                ["default"] = new[]
+                {
+                    new Translation(string.Empty, "default", "key A", "default A"),
+                    new Translation(string.Empty, "default", "key C", "default C")
+                },
+                ["en"] = new[]
+                {
+                    new Translation(string.Empty, "en", "key A", "en A"),
+                    new Translation(string.Empty, "en", "key B", "en B"),
+                    new Translation(string.Empty, "en", "key C", "default C")
+                },
+                ["zzz"] = new[]
+                {
+                    new Translation(string.Empty, "zzz", "key A", "zzz A"),
+                    new Translation(string.Empty, "zzz", "key C", "default C")
+                }
+            };
+            expected["en-us"] = expected["en"].ToArray();
+            return expected;
+        }
+
+        /// <summary>Get whether two translations have the same public values.</summary>
+        /// <param name="a">The first translation to compare.</param>
+        /// <param name="b">The second translation to compare.</param>
+        private bool CompareEquality(Translation a, Translation b)
+        {
+            return a.Key == b.Key && a.ToString() == b.ToString();
+        }
+
+        /// <summary>Get the default placeholder text when a translation is missing.</summary>
+        /// <param name="key">The translation key.</param>
+        private string GetPlaceholderText(string key)
+        {
+            return string.Format(Translation.PlaceholderText, key);
+        }
+
+
+        /*********
+        ** Test models
+        *********/
+        /// <summary>A model used to test token support.</summary>
+        private class TokenModel
+        {
+            /// <summary>A sample token property.</summary>
+            public string Start { get; set; }
+
+            /// <summary>A sample token property.</summary>
+            public string Middle { get; set; }
+
+            /// <summary>A sample token field.</summary>
+            public string End;
+        }
+    }
+}