Refactor test configuration to standardize instance naming and improve clarity in documentation (#10142)

Author: andreasjordan

.github/CONTRIBUTING-TESTING.md

@@ -151,10 +151,6 @@ $config['InstanceHadr'] = "YourServer\Instance2"
 # For tests that restart SQL Server (use with caution!)
 $config['InstanceRestart'] = "YourServer\Instance2"
 
-# Legacy support - some older tests still use these
-$config['instance1'] = $config['InstanceSingle']
-$config['instance2'] = $config['InstanceMulti2']
-
 # ============================================
 # Authentication
 # ============================================
@@ -175,9 +171,6 @@ $config['Defaults']['*:DestinationSqlCredential'] = $config['SqlCred']
 # Test Infrastructure
 # ============================================
 
-# Computer name for certain tests
-$config['dbatoolsci_computer'] = $env:COMPUTERNAME
-
 # Temp directory for test files
 # IMPORTANT: For remote instances, use a network share accessible by both
 # the SQL Server service account AND your PowerShell session

.github/copilot-instructions.md

@@ -431,9 +431,9 @@ Context "Parameter validation" {
 ## Environment Variables & Test Config
 
 **AppVeyor test instances:**
-- `$script:instance1` = SQL Server 2008 R2
-- `$script:instance2` = SQL Server 2016
-- `$script:instance3` = SQL Server 2017
+- `$TestConfig.InstanceSingle` = SQL Server 2022
+- `$TestConfig.InstanceMulti1` = SQL Server 2022
+- `$TestConfig.InstanceMulti2` = SQL Server 2017
 
 **GitHub Actions:**
 - Linux: `localhost`, `localhost:14333` (Docker containers)

.github/prompts/style.md

@@ -353,11 +353,11 @@ Import-Module C:\gallery\dbatools.library
 $TestConfig = Get-TestConfig
 
 # 3. Now you can use $TestConfig properties in your tests
-$TestConfig.instance1    # First test SQL instance
-$TestConfig.instance2    # Second test SQL instance
-$TestConfig.instance3    # Third test SQL instance
-$TestConfig.SqlCred      # Test credentials, all connections need this
-$TestConfig.Temp         # Temp directory for test files
+$TestConfig.InstanceSingle    # Test SQL instance for tests that only need one instance
+$TestConfig.InstanceMulti1    # First test SQL instance for tests that need multiple instances
+$TestConfig.InstanceMulti2    # Second test SQL instance for tests that need multiple instances
+$TestConfig.SqlCred           # Test credentials, all connections need this
+$TestConfig.Temp              # Temp directory for test files
 
 # 4. Set the default params for sqlcred
 $PSDefaultParameterValues["*:SqlCredential"] = $TestConfig.SqlCred

CONTRIBUTING.md

@@ -130,24 +130,18 @@ You can inspect/copy/cannibalize existing tests. You'll see that every test file
 
 ## AppVeyor Environment
 
-AppVeyor is hooked up to test any commit, including PRs. Each commit triggers 5 builds, each referred to as a "scenario". We have the scenarios setup where the dbatools log is published as an artifact should you need to view why test are failing.
+AppVeyor is hooked up to test any commit, including PRs. Each commit triggers several builds, each referred to as a "scenario". We have the scenarios setup where the dbatools log is published as an artifact should you need to view why test are failing.
 
-- 2008R2 : a server with a single SQL Server 2008 R2 Express Edition instance available ($script:instance1)
-- 2016 : a server with a single SQL Server 2016 Developer Edition instance available ($script:instance2)
-- 2016_service: used to test service restarts
-- 2016_2017 : a server with two instances available, 2016 and 2017 Developer Edition
-- default: a server with two instances available, one SQL Server 2008 R2 Express Edition and a SQL Server 2016 Developer Edition
+- SINGLE: a server with a single SQL Server 2022 instance available ($TestConfig.InstanceSingle)
+- MULTI: a server with two instances (SQL Server 2022 and SQL Server 2017) available for tests that need multiple instances ($TestConfig.InstanceMulti1 and $TestConfig.InstanceMulti2)
+- COPY: a server with two instances (SQL Server 2017 and SQL Server 2022) available for tests that need multiple instances ($TestConfig.InstanceCopy1 and $TestConfig.InstanceCopy2)
+- HADR: a single SQL Server 2022 instance available with Hadr configured ($TestConfig.InstanceHadr)
+- RESTART: used to test service restarts ($TestConfig.InstanceRestart)
+- 2008R2SP2Express: a server with a single SQL Server 2008 R2 Express Edition available to test some commands against an old version ($TestConfig.InstanceSingle)
+- default: a server with no instance for all tests that don't need a running instance
 
 Builds are split among "scenario"(s) because not every test requires everything to be up and running, and resources on AppVeyor are constrained.
-
-Ideally:
-
-1. Whenever possible, write UnitTests.
-2. You should write IntegrationTests ideally running in **EITHER** the 2008R2 or the 2016 "scenario".
-3. Default and 2016_2017 are the most resource constrained and are left to run the Copy-* commands which are the only ones **needing** two active instances.
-4. If you want to write tests that, e.g, target **BOTH** 2008R2 and 2016, try to avoid writing tests that need both instances to be active at the same time.
-
-AppVeyor is set up to recognize what "scenario" is required by your test, simply inspecting for the presence of combinations of `$script:instance1`, `$script:instance2` and `$script:instance3`. If you need to fall into case (4), write two test files, e.g. _Get-DbaFoo.first.Tests.ps1_ (targeting `$script:instance1` only) and _Get-DbaFoo.second.Tests.ps1_ (targeting `$script:instance2` only).
+AppVeyor is set up to recognize what "scenario" is required by your test, simply inspecting for the presence of $TestConfig.Instance*.
 
 Most PRs will target `public/*.ps1` files to add functionality or resolve bugs.
 Our test runner will try and figure out what tests needs to be run based on the files modified in the PR, plus all the dependencies.

private/testing/Get-TestConfig.ps1

@@ -61,18 +61,18 @@ function Get-TestConfig {
     } elseif ($env:CODESPACES -or ($env:TERM_PROGRAM -eq 'vscode' -and $env:REMOTE_CONTAINERS)) {
         $null = Set-DbatoolsInsecureConnection
 
-        $config['Instance1'] = "dbatools1"
-        $config['Instance2'] = "dbatools2"
+        $config['InstanceSingle'] = "dbatools1"
+        $config['InstanceMulti1'] = "dbatools1"
+        $config['InstanceMulti2'] = "dbatools2"
 
         $config['SqlCred'] = [PSCredential]::new('sa', (ConvertTo-SecureString $env:SA_PASSWORD -AsPlainText -Force))
         $config['Defaults']['*:SqlCredential'] = $config['SqlCred']
         $config['Defaults']['*:SourceSqlCredential'] = $config['SqlCred']
         $config['Defaults']['*:DestinationSqlCredential'] = $config['SqlCred']
     } elseif ($env:GITHUB_WORKSPACE) {
-        $config['DbaToolsCi_Computer'] = "localhost"
-
-        $config['Instance1'] = "localhost"
-        $config['Instance2'] = "localhost:14333"
+        $config['InstanceSingle'] = "localhost"
+        $config['InstanceMulti1'] = "localhost"
+        $config['InstanceMulti2'] = "localhost:14333"
 
         $config['SQLUserName'] = $null  # placeholders for -SqlCredential testing
         $config['SQLPassword'] = $null

tests/CLAUDE.md

@@ -16,11 +16,11 @@ Import-Module C:\gallery\dbatools.library
 $TestConfig = Get-TestConfig
 
 # 3. Now you can use $TestConfig properties in your tests
-$TestConfig.instance1    # First test SQL instance
-$TestConfig.instance2    # Second test SQL instance
-$TestConfig.instance3    # Third test SQL instance
-$TestConfig.SqlCred      # Test credentials, all connections need this
-$TestConfig.Temp         # Temp directory for test files
+$TestConfig.InstanceSingle    # Test SQL instance for tests that only need one instance
+$TestConfig.InstanceMulti1    # First test SQL instance for tests that need multiple instances
+$TestConfig.InstanceMulti2    # Second test SQL instance for tests that need multiple instances
+$TestConfig.SqlCred           # Test credentials, all connections need this
+$TestConfig.Temp              # Temp directory for test files
 # 4. Set the default paras for sqlcred
 $PSDefaultParameterValues["*:SqlCredential"] = $TestConfig.SqlCred
 ```

tests/constants.local.ps1.example

@@ -4,8 +4,13 @@
 # Modify the $config hashtable to include your custom configurations.
 
 # Define your local SQL Server instances
-$config['instance1'] = "localhost\SQLInstance1"    # Replace with your first SQL Server instance
-$config['instance2'] = "localhost\SQLInstance2"    # Replace with your second SQL Server instance
+$config['InstanceSingle'] = "localhost\SQLInstance1"
+$config['InstanceMulti1'] = "localhost\SQLInstance1"
+$config['InstanceMulti2'] = "localhost\SQLInstance2"
+$config['InstanceCopy1'] = "localhost\SQLInstance1"
+$config['InstanceCopy2'] = "localhost\SQLInstance2"
+$config['InstanceHadr'] = "localhost\SQLInstance1"
+$config['InstanceRestart'] = "localhost\SQLInstance1"
 
 # SQL Server credentials
 # Replace 'YourPassword' with your actual password and 'sa' with your username if different
@@ -17,9 +22,6 @@ $config['Defaults'] = [System.Management.Automation.DefaultParameterDictionary]@
     "*:SqlCredential" = $config['SqlCred']
 }
 
-# Additional configurations
-$config['dbatoolsci_computer'] = "localhost"    # Replace if your CI computer is different
-
 # If using SQL authentication for Instance2, specify the username and password
 $config['SQLUserName'] = $null        # Replace with username if applicable
 $config['SQLPassword'] = $null        # Replace with password if applicable