microsoft · Michael Smith (Exolun) · Sep 10, 2024 · Aug 1, 2024 · Aug 1, 2024 · Aug 1, 2024
diff --git a/.gitignore b/.gitignore
@@ -1 +1,2 @@
-.vscode
+.vscode
+/Tests/Test-Results.xml
diff --git a/README.md b/README.md
@@ -2,6 +2,18 @@
 
 This PowerShell module contains tools for managing and automating your Unity installs and projects.
 
+# Table of Contents
+
+1. [Unity Setup Powershell Module](#unity-setup-powershell-module)
+2. [Builds](#builds)
+3. [Installation](#installation)
+4. [Using](#using)
+5. [Feedback](#feedback)
+6. [Contributing](#contributing)
+7. [Testing](#testing)
+8. [Reporting Security Issues](#reporting-security-issues)
+
+
 ## Builds
 
 ### Master
@@ -236,6 +248,14 @@ When you submit a pull request, a CLA-bot will automatically determine whether y
 
 This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.
 
+
+## Testing
+
+This project includes Pester test runners for both unit tests and end to end tests - which can test against real Unity projects via environment variables.
+
+To learn more about how to run and write tests, please refer to the [Test Runner Guide](./Tests/README.md).
+
+
 # Reporting Security Issues
 
 Security issues and bugs should be reported privately, via email, to the Microsoft Security Response Center (MSRC) at [secure@microsoft.com](mailto:secure@microsoft.com). You should receive a response within 24 hours. If for some reason you do not, please follow up via email to ensure we received your original message. Further information, including the [MSRC PGP](https://technet.microsoft.com/en-us/security/dn606155) key, can be found in the [Security TechCenter](https://technet.microsoft.com/en-us/security/default).
diff --git a/Tests/Data/manifest.json b/Tests/Data/manifest.json
@@ -0,0 +1,22 @@
+{
+  "scopedRegistries": [
+    {
+      "name": "TestRegistry",
+      "url": "https://placeholder/url",
+      "scopes": [
+        "com.azure",
+        "com.microsoft",
+        "org.nuget"
+      ]
+    }
+  ],
+  "dependencies": {
+    "com.example.packageA": "2.3.4",
+    "org.sample.libB": "5.6.7",
+    "net.test.pluginC": "0.9.1"
+  },
+  "testables": [
+    "com.example.testA",
+    "org.sample.testB"
+  ]
+}
diff --git a/Tests/Data/manifestlike.json b/Tests/Data/manifestlike.json
@@ -0,0 +1,26 @@
+{
+  "scopedRegistries": [
+    {
+      "name": "TestRegistry",
+      "url": "https://placeholder/url",
+      "scopes": [
+        "com.azure",
+        "com.microsoft",
+        "org.nuget"
+      ]
+    }
+  ],
+  "zooAnimals": {
+    "lion": "Panthera leo",
+    "elephant": "Loxodonta africana",
+    "zebra": "Equus quagga"
+  },
+  "favoritePrimeNumbers": [
+    2,
+    3,
+    5,
+    7,
+    11,
+    13
+  ]
+}
diff --git a/Tests/E2ETests/Update-UnityPackageManagerConfig.Tests.ps1 b/Tests/E2ETests/Update-UnityPackageManagerConfig.Tests.ps1
@@ -0,0 +1,79 @@
+Describe 'Update-UnityPackageManagerConfig' {
+    BeforeAll {
+        Import-Module (Join-Path $PSScriptRoot '..\..\UnitySetup\UnitySetup.psd1') -Force
+    }
+
+    Context 'E2E Validation of manifest/folder targets' {
+        It 'supports a root folder target' {
+            { Update-UnityPackageManagerConfig -SearchPath $env:TEST_UNITY_FOLDERPATH -SearchDepth 5 } | Should -Not -Throw
+        }
+
+        It 'supports a single manifest target' {
+            { Update-UnityPackageManagerConfig -ProjectManifestPath $env:TEST_UNITY_MANIFESTPATH } | Should -Not -Throw
+        }
+
+        It 'supports a search target with multiple manifests' {
+            { Update-UnityPackageManagerConfig -SearchPath $env:TEST_UNITY_MULTIFOLDERPATH -SearchDepth 5 } | Should -Not -Throw
+        }
+
+        It 'supports a single manifest-like target (any JSON file with valid scoped registries)' {
+            { Update-UnityPackageManagerConfig -ProjectManifestPath $env:TEST_UNITY_MANIFESTLIKEPATH } | Should -Not -Throw
+        }
+
+        It 'should throw if manifest path is a folder, not a file' {
+            { Update-UnityPackageManagerConfig -ProjectManifestPath $env:TEST_UNITY_FOLDERPATH } | Should -Throw "* is not a valid file"
+        }
+    }
+
+    Context 'E2E Validation of AzureSubscriptionID options' {
+        It 'should throw on malformed AzureSubscription guid' {
+            { Update-UnityPackageManagerConfig -ProjectManifestPath $env:TEST_UNITY_MANIFESTPATH -AzureSubscription "abcd" } | Should -Throw "*Unrecognized Guid format*"
+        }
+
+        It 'should accept a valid AzureSubscription guid' {
+            { Update-UnityPackageManagerConfig -ProjectManifestPath $env:TEST_UNITY_MANIFESTPATH -AzureSubscription $env:TEST_AZURESUBSCRIPTION_ID } | Should -Not -Throw
+        }
+    }
+
+    Context 'E2E Validation of AutoClean parameter' {
+        It 'should run with AutoClean enabled' {
+            { Update-UnityPackageManagerConfig -ProjectManifestPath $env:TEST_UNITY_MANIFESTPATH -AutoClean } | Should -Not -Throw
+        }
+    }
+
+    Context 'E2E Validation of ManualPAT parameter' {
+        It 'should run with ManualPAT enabled' {
+            { Update-UnityPackageManagerConfig -ProjectManifestPath $env:TEST_UNITY_MANIFESTPATH -ManualPAT } | Should -Not -Throw
+        }
+    }
+
+    Context 'E2E Validation of VerifyOnly parameter' {
+        It 'should run with VerifyOnly enabled' {
+            { Update-UnityPackageManagerConfig -ProjectManifestPath $env:TEST_UNITY_MANIFESTPATH -VerifyOnly } | Should -Not -Throw
+        }
+    }
+
+    Context 'Combination of parameters' {
+        It 'should run with AutoClean, ManualPAT, and VerifyOnly enabled' {
+            { Update-UnityPackageManagerConfig -ProjectManifestPath $env:TEST_UNITY_MANIFESTPATH -AutoClean -ManualPAT -VerifyOnly } | Should -Not -Throw
+        }
+
+        It 'should run with SearchDepth, PATLifetime, and AzureSubscription parameters' {
+            { Update-UnityPackageManagerConfig -SearchPath $env:TEST_UNITY_FOLDERPATH -SearchDepth 7 -PATLifetime 30 -AzureSubscription $env:TEST_AZURESUBSCRIPTION_ID } | Should -Not -Throw
+        }
+    }
+
+    Context 'Edge cases for parameter values' {
+        It 'should throw if SearchDepth is negative' {
+            { Update-UnityPackageManagerConfig -SearchPath $env:TEST_UNITY_FOLDERPATH -SearchDepth -1 } | Should -Throw '*Cannot convert value "-1" to type "System.UInt32"*'
+        }
+
+        It 'should throw if PATLifetime is zero' {
+            { Update-UnityPackageManagerConfig -ProjectManifestPath $env:TEST_UNITY_MANIFESTPATH -PATLifetime 0 } | Should -Throw "*PATLifetime must be greater than zero*"
+        }
+
+        It 'should throw if AzureSubscription is empty GUID' {
+            { Update-UnityPackageManagerConfig -ProjectManifestPath $env:TEST_UNITY_MANIFESTPATH -AzureSubscription [guid]::Empty } | Should -Throw "*Unrecognized Guid format*"
+        }
+    }
+}
diff --git a/Tests/README.md b/Tests/README.md
@@ -0,0 +1,64 @@
+# Test Runner Guide
+
+This document provides an overview of the test runner setup and how to use it for both end-to-end (E2E) and unit testing in this project.
+
+## Table of Contents
+
+1. [Overview](#overview)
+2. [Environment Setup](#environment-setup)
+3. [Running the Tests](#running-the-tests)
+   - [End-to-End Tests](#end-to-end-tests)
+   - [Unit Tests](#unit-tests)
+4. [Folder Structure](#folder-structure)
+5. [Additional Information](#additional-information)
+
+## Overview
+
+The test runner is designed to facilitate both end-to-end and unit testing on real Unity project targets using UnitySetup cmdlets. Including real generation of Unity Package Manager auth tokens. (You may need to delete your .toml file locally for fresh runs)
+
+## Environment Setup (End to End Tests)
+
+Before running the tests, ensure that you have one or more Unity projects locally that can serve for the following environment variables:
+
+- `TEST_UNITY_FOLDERPATH`: Path to the root folder of a Unity project.
+- `TEST_UNITY_MANIFESTPATH`: Path to a valid Unity project manifest.
+- `TEST_UNITY_MULTIFOLDERPATH`: Path to the root folder of a Unity project with multiple manifests in subfolders less than 5 directories deep.
+- `TEST_UNITY_MANIFESTLIKEPATH`: Path to a valid Unity project manifest-like file. (Any valid JSON file with scoped registries)
+- `TEST_AZURESUBSCRIPTION_ID`: Azure Subscription ID required for certain test scenarios.
+
+These environment variables can be set interactively when running the tests or manually before running the test scripts.
+
+## Running the Tests
+
+### End-to-End Tests
+
+The end-to-end tests are located in the `E2ETests` folder. These tests validate the entire workflow, including real environment variables.
+
+To run the end-to-end tests:
+
+```powershell
+cd Tests
+.\e2etests.ps1
+```
+
+This script will import the necessary modules and run all tests in the `E2ETests` folder, using the provided environment variables.
+
+### Unit Tests
+
+The unit tests are located in the `UnitTests` folder. These tests use mocked data and functions to isolate and validate individual components.
+
+To run the unit tests:
+
+```powershell
+cd Tests
+.\unittests.ps1
+```
+
+This script will run all unit tests in the `UnitTests` folder, using mock functions and predefined input/output.
+
+## Additional Information
+
+- The test scripts utilize `Pester` and `PSScriptAnalyzer` modules. Ensure these modules are installed and available in your environment before running the tests.
+- Test results can be output to the console or captured programmatically using the `-PassThru` switch.
+
+For further customization, review the provided test scripts and modify the parameters or mocks as needed.
diff --git a/Tests/UnitTests/Find-UnitySetupInstaller.Tests.ps1 b/Tests/UnitTests/Find-UnitySetupInstaller.Tests.ps1
@@ -0,0 +1,48 @@
+Describe 'Find-UnitySetupInstaller' {
+
+    BeforeEach {
+        Import-Module "$PSScriptRoot\..\..\UnitySetup\UnitySetup.psd1" -Force
+    }
+
+    Context 'Input Validation' {
+        It 'throws on invalidly formatted version' {
+            { Find-UnitySetupInstaller -Version "" } | Should -Throw "Cannot process argument transformation*"
+        }
+    }
+
+    Context 'Function Execution' {
+        It 'throws on non-existent version' {
+            { Find-UnitySetupInstaller -Version "1.2.3f1" } | Should -Throw "Could not find archives for Unity version*"
+        }
+
+        It 'finds an existing version' {
+            # https://unity.com/releases/editor/whats-new/2022.3.15 lists 13 for Windows, but we don't support Mac_Server
+            Find-UnitySetupInstaller -Version "2022.3.15f1" -ExplicitOS Windows | Should -HaveCount 12
+        }
+
+        # TODO: Support Mac ARM as a platform
+        # It 'does not find VisionOS before supported (Mac)' {
+        #     Find-UnitySetupInstaller -Version "2022.3.15f1" -Components VisionOS -ExplicitOS Mac | Should -HaveCount 0
+        # }
+
+        # It 'does find VisionOS once supported (Mac)' {
+        #     Find-UnitySetupInstaller -Version "2022.3.18f1" -Components VisionOS -ExplicitOS Mac | Should -HaveCount 1
+        # }
+
+        It 'does not find VisionOS before supported (Windows)' {
+            Find-UnitySetupInstaller -Version "2022.3.18f1" -Components VisionOS -ExplicitOS Windows `
+            | Should -HaveCount 0
+        }
+
+        It 'finds VisionOS once supported (Windows, explicit)' {
+            Find-UnitySetupInstaller -Version "2022.3.21f1" -Components VisionOS -ExplicitOS Windows `
+            | Should -HaveCount 1
+        }
+
+        It 'finds VisionOS once supported (Windows, implicit)' {
+            Find-UnitySetupInstaller -Version "2022.3.21f1" -ExplicitOS Windows `
+            | Where-Object -Property ComponentType -Eq VisionOS `
+            | Should -HaveCount 1
+        }
+    }
+}