Nexus-Mods · halgari · Oct 2, 2025 · Oct 2, 2025 · Oct 6, 2025 · Oct 6, 2025
diff --git a/.github/workflows/clean_environment_tests.yaml b/.github/workflows/clean_environment_tests.yaml
@@ -29,9 +29,30 @@ jobs:
         run: exit 1
 
   build-and-test:
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os_name: linux
+            runs_on: [ self-hosted, Linux, x64 ]
+            shell: bash
+          - os_name: windows
+            runs_on: [ self-hosted, Windows, x64 ]
+            shell: powershell
+    runs-on: ${{ matrix.runs_on }}
     if: github.event_name == 'push' || github.event.pull_request.draft == false
-    uses: Nexus-Mods/NexusMods.App.Meta/.github/workflows/dotnet-build-and-test-with-osx.yaml@main
-    with:
-      extra-test-args: "--blame-hang-timeout 20m"
-      test-filter: "RequiresNetworking!=True&FlakeyTest!=True"
-      codecov-flags: ",clean_environment_tests"
+
+    env:
+      NEXUS_API_KEY: ${{ secrets.NEXUS_API_KEY }}
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Restore
+        run: dotnet restore
+
+      - name: Build
+        run: dotnet build --configuration Release --no-restore
+
+      - name: Test
+        run: dotnet test --configuration Release --no-build --verbosity normal
diff --git a/.github/workflows/networking_tests.yaml b/.github/workflows/networking_tests.yaml
diff --git a/Directory.Packages.props b/Directory.Packages.props
@@ -24,10 +24,10 @@
     <PackageVersion Include="NexusMods.MnemonicDB.Abstractions" Version="0.28.2" />
     <PackageVersion Include="NexusMods.Hashing.xxHash3.Paths" Version="3.0.4" />
     <PackageVersion Include="NexusMods.Hashing.xxHash3" Version="3.0.4" />
-    <PackageVersion Include="NexusMods.Archives.Nx" Version="0.6.4" />
-    <PackageVersion Include="NexusMods.Paths" Version="0.20.0" />
-    <PackageVersion Include="NexusMods.Paths.Extensions.Nx" Version="0.20.0" />
-    <PackageVersion Include="NexusMods.Paths.TestingHelpers" Version="0.20.0" />
+    <PackageVersion Include="NexusMods.Archives.Nx" Version="0.6.5" />
+    <PackageVersion Include="NexusMods.Paths" Version="0.22.5" />
+    <PackageVersion Include="NexusMods.Paths.Extensions.Nx" Version="0.22.5" />
+    <PackageVersion Include="NexusMods.Paths.TestingHelpers" Version="0.22.5" />
     <PackageVersion Include="NexusMods.Telemetry.OpenTelemetry" Version="1.0.0" />
     <PackageVersion Include="FomodInstaller.Interface" Version="1.2.0" />
     <PackageVersion Include="FomodInstaller.Scripting.XmlScript" Version="1.0.0" />
@@ -56,6 +56,7 @@
     <PackageVersion Include="OpenTelemetry.Extensions.Hosting" Version="1.12.0" />
     <PackageVersion Include="Polly.Core" Version="8.6.3" />
     <PackageVersion Include="Polly" Version="8.6.3" />
+    <PackageVersion Include="TUnit.Core" Version="0.57.24" />
     <PackageVersion Include="Verify" Version="30.11.0" />
     <PackageVersion Include="Verify.TUnit" Version="30.11.0" />
     <PackageVersion Include="YamlDotNet" Version="16.3.0" />
@@ -163,4 +164,4 @@
     <PackageVersion Include="TransparentValueObjects" Version="1.1.0" />
     <PackageVersion Include="TransparentValueObjects.Abstractions" Version="1.1.0" />
   </ItemGroup>
-</Project>
+</Project>
diff --git a/NexusMods.App.sln b/NexusMods.App.sln
@@ -258,6 +258,8 @@ Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "NexusMods.Games.CreationEng
 EndProject
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "NexusMods.Backend.Tests", "tests\NexusMods.Backend.Tests\NexusMods.Backend.Tests.csproj", "{9BA054EF-E912-49AB-8889-AE807713BD74}"
 EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "NexusMods.Games.IntegrationTestFramework", "tests\Games\NexusMods.Games.IntegrationTestFramework\NexusMods.Games.IntegrationTestFramework.csproj", "{87664A03-EFA8-41C5-9407-E8E0E45402F6}"
+EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
 		Debug|Any CPU = Debug|Any CPU
@@ -672,6 +674,10 @@ Global
 		{9BA054EF-E912-49AB-8889-AE807713BD74}.Debug|Any CPU.Build.0 = Debug|Any CPU
 		{9BA054EF-E912-49AB-8889-AE807713BD74}.Release|Any CPU.ActiveCfg = Release|Any CPU
 		{9BA054EF-E912-49AB-8889-AE807713BD74}.Release|Any CPU.Build.0 = Release|Any CPU
+		{87664A03-EFA8-41C5-9407-E8E0E45402F6}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{87664A03-EFA8-41C5-9407-E8E0E45402F6}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{87664A03-EFA8-41C5-9407-E8E0E45402F6}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{87664A03-EFA8-41C5-9407-E8E0E45402F6}.Release|Any CPU.Build.0 = Release|Any CPU
 	EndGlobalSection
 	GlobalSection(SolutionProperties) = preSolution
 		HideSolutionNode = FALSE
@@ -791,6 +797,7 @@ Global
 		{B7A8F2D3-1C4E-4F6B-9A2D-E5B6C7D8F9A0} = {52AF9D62-7D5B-4AD0-BA12-86F2AA67428B}
 		{8E8D0E1E-598D-459C-8624-DA1F8F4127D3} = {05B06AC1-7F2B-492F-983E-5BC63CDBF20D}
 		{9BA054EF-E912-49AB-8889-AE807713BD74} = {52AF9D62-7D5B-4AD0-BA12-86F2AA67428B}
+		{87664A03-EFA8-41C5-9407-E8E0E45402F6} = {05B06AC1-7F2B-492F-983E-5BC63CDBF20D}
 	EndGlobalSection
 	GlobalSection(ExtensibilityGlobals) = postSolution
 		SolutionGuid = {9F9F8352-34DD-42C0-8564-EE9AF34A3501}

diff --git a/docs/developers/development-guidelines/RunningIntegrationTests.md b/docs/developers/development-guidelines/RunningIntegrationTests.md
@@ -0,0 +1,38 @@
+# Running Integration Tests
+
+The Nexus Mods app has certain tests marked as "integration tests", these are tests that require a valid copy of a game
+in order to perform certain tests. These tests are separate from unit tests that attempt to mock various parts of the game
+or introduce "fake game" data for testing. 
+
+## Overview
+
+The integration tests run by storing copies of game files in `.nx` archives hosted in a "game images" folder. This folder
+has the structure of `{root}/{Store}/{LocatorId}.nx`. So for steam these files are in `{root}/Steam/1234567890.nx` for Manifest ID
+`1234567890`.
+
+During tests a custom `IFileSystem` is created that uses these game images as a base, and stores any modified files in memory, 
+each test is then given a clean copy of the game files. Each test can run whatever operations it needs to run, and then
+validate behavior against actual game files. Since NMA uses this `IFileSystem` abstraction across the entire app, it is possible
+to use these game images as-is without extracting any files to disk. Tests can even be created to simulate a disk state
+that does not match the reported Steam state. 
+
+## Setup
+In order to run the integration tests for a given game you must first create the game images. For steam this is done by
+running the CLI command `steam manifest pack-game -a "{Game Name}" -o "{ImagesRoot}"`. Note that "Game Name" is the english
+name of the game, such as "Skyrim Special Edition". The output folder is the base folder, not the Steam sub-folder. This
+CLI command will download all the manifests for the given game and pack the game files into `.nx` archives. Next you must
+specify the root folder for tests, via the environment variable `NMA_INTEGRATION_BASE_PATH` environment variable.
+
+## Running Tests
+
+Now simply navigate to a specific integration test folder and run `dotnet run` to run the tests via tUnit. The Integration tests 
+will not run at all if the environment variable `NMA_INTEGRATION_BASE_PATH` is not set, and will error if the correct game
+images are not present. This silent failure with the environment variable is intentional, so that CI runs in various environments
+without failures and without having specify complex filters in the test runners.  The NMA project hosts all tgame images
+on the test runner for the integration tests, speak with the app developers if there are additional manifests requried for testing.
+
+## Create new tests
+To create new tests, create a class that inherits from `AGameIntegrationTest`. Specify which games to run the test on
+via attributes attached to the class. These attributes then generate data that is used to parameterize the test. Be liberal
+with the creation of new test attributes, as they are an easy extension point for creating new inputs and for verifying
+behavior across multiple games and platforms.
diff --git a/src/NexusMods.Abstractions.GameLocators/GameLocationsRegister.cs b/src/NexusMods.Abstractions.GameLocators/GameLocationsRegister.cs
@@ -163,9 +163,11 @@ public IReadOnlyCollection<LocationId> GetNestedLocations(LocationId id)
     /// <returns></returns>
     public GamePath ToGamePath(AbsolutePath absolutePath)
     {
+        absolutePath = absolutePath.FileSystem.Unmap(absolutePath);
         return _locations.Values.Where(location => absolutePath.StartsWith(location.ResolvedPath))
             .Select(desc => new GamePath(desc.Id, absolutePath.RelativeTo(desc.ResolvedPath)))
             .MinBy(gamePath => gamePath.Path.Path.Length);
+
     }
 
     /// <summary>

diff --git a/src/NexusMods.Backend/FileExtractor/Extractors/ManagedZipExtractor.cs b/src/NexusMods.Backend/FileExtractor/Extractors/ManagedZipExtractor.cs
@@ -1,4 +1,5 @@
 using System.Diagnostics;
+using System.IO.Compression;
 using System.IO.Hashing;
 using System.Runtime.InteropServices;
 using System.Text;
@@ -8,6 +9,7 @@
 using NexusMods.FileExtractor;
 using NexusMods.Paths;
 using NexusMods.Sdk.IO;
+using ZipFile = ICSharpCode.SharpZipLib.Zip.ZipFile;
 
 namespace NexusMods.Backend.FileExtractor.Extractors;
 

diff --git a/src/NexusMods.Backend/FileExtractor/Extractors/SevenZipExtractor.cs b/src/NexusMods.Backend/FileExtractor/Extractors/SevenZipExtractor.cs
@@ -53,7 +53,7 @@ public SevenZipExtractor(
         _temporaryFileManager = fileTemporaryFileManager;
         _processRunner = processRunner;
         _osInformation = osInformation;
-
+        
         _exePath = GetExtractorExecutable(fileSystem, osInformation);
         logger.LogDebug("Using extractor at {ExtractorExecutable}", _exePath);
     }
@@ -182,6 +182,7 @@ internal static void To7ZipWindowsExtractionPath(Span<char> input)
     {
         var pathsWithInvalidCharacters = new List<(string fileName, bool isDirectory)>();
 
+        source = source.FileSystem.Map(source);
         // NOTE(erri120): "l -ba" is an undocumented command that skips the table header and footer
         var process = Cli
             .Wrap(_exePath)
@@ -242,6 +243,8 @@ internal static bool TryParseListCommandOutput(ReadOnlySpan<char> line, [NotNull
 
     private async ValueTask ExtractArchive(AbsolutePath source, AbsolutePath destination, CancellationToken cancellationToken)
     {
+        destination = destination.FileSystem.Map(destination);
+        source = source.FileSystem.Map(source);
         // NOTE(erri120): Using "-bsp1" to redirect the progress line to stdout
         var process = Cli
             .Wrap(_exePath)

diff --git a/src/NexusMods.Backend/FileExtractor/FileExtractor.cs b/src/NexusMods.Backend/FileExtractor/FileExtractor.cs
@@ -76,6 +76,7 @@ public async Task ExtractAllAsync(IStreamFactory sFn, AbsolutePath dest, Cancell
             catch (Exception ex)
             {
                 _logger.LogError(ex, "While extracting via {Extractor}", extractor);
+                throw;
             }
         }
-Original file line number
+Diff line change
@@ Expand Up @@
                 catch (Exception ex)
                 {
                     _logger.LogError(ex, "While extracting via {Extractor}", extractor);
+                    throw;
                 }
             }
@@ Expand Down @@