From 0c81477dc72e0baa9c4ecd0d095aba9e3bc78168 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sun, 25 Jan 2026 21:27:37 +0000
Subject: [PATCH 1/5] Initial plan


From aa8fafa65ea43c49f1c93beede26051f52bbacfb Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sun, 25 Jan 2026 21:33:14 +0000
Subject: [PATCH 2/5] Restructure tests folder and split helpers by domain

- Create domain folders: Core/, Steps/, Packaging/, Examples/
- Move test files to appropriate domain folders
- Create domain helper files:
  - Steps/_testHelpers.Steps.ps1 (contains New-IdleTestStepMetadata)
  - Providers/_testHelpers.Providers.ps1 (empty, ready for future use)
- Update main _testHelpers.ps1 to dot-source domain helpers
- Update all test file paths to use parent directory for helpers
- All tests remain discoverable by Pester
- PSScriptAnalyzer passes with no issues

Co-authored-by: blindzero <13959569+blindzero@users.noreply.github.com>
---
 .../CapabilityDeprecation.Tests.ps1           |  2 +-
 .../Copy-IdleRedactedObject.Tests.ps1         |  2 +-
 tests/{ => Core}/Export-IdlePlan.Tests.ps1    |  2 +-
 .../Get-IdleProviderCapabilities.Tests.ps1    |  2 +-
 tests/{ => Core}/ImportIdLE.Tests.ps1         |  2 +-
 .../Invoke-IdlePlan.Condition.Tests.ps1       |  2 +-
 ...Invoke-IdlePlan.ExecutionOptions.Tests.ps1 |  4 +-
 .../Invoke-IdlePlan.Retry.Tests.ps1           |  4 +-
 .../Invoke-IdlePlan.StepRegistry.Tests.ps1    |  2 +-
 tests/{ => Core}/Invoke-IdlePlan.Tests.ps1    |  2 +-
 .../New-IdleLifecycleRequest.Tests.ps1        |  2 +-
 .../New-IdlePlan.Capabilities.Tests.ps1       |  2 +-
 tests/{ => Core}/New-IdlePlan.Tests.ps1       |  2 +-
 .../{ => Core}/Redaction.Boundaries.Tests.ps1 |  2 +-
 .../Resolve-IdleStepMetadataCatalog.Tests.ps1 |  2 +-
 .../Resolve-IdleWorkflowTemplates.Tests.ps1   |  2 +-
 tests/{ => Core}/Test-IdleCondition.Tests.ps1 |  2 +-
 tests/{ => Core}/Test-IdleWorkflow.Tests.ps1  |  2 +-
 .../{ => Examples}/WorkflowSamples.Tests.ps1  |  2 +-
 .../{ => Packaging}/ModuleManifests.Tests.ps1 |  2 +-
 tests/{ => Packaging}/ModuleSurface.Tests.ps1 |  2 +-
 .../New-IdleReleaseArtifact.Tests.ps1         |  2 +-
 tests/{ => Packaging}/PublicApi.Tests.ps1     |  2 +-
 tests/Providers/_testHelpers.Providers.ps1    | 17 +++++
 .../Invoke-IdleStepAuthSession.Tests.ps1      |  0
 ...Invoke-IdleStepEnsureEntitlement.Tests.ps1 |  2 +-
 .../Invoke-IdleStepMailboxGetInfo.Tests.ps1   |  2 +-
 ...IdleStepMailboxOutOfOfficeEnsure.Tests.ps1 |  2 +-
 ...Invoke-IdleStepMailboxTypeEnsure.Tests.ps1 |  2 +-
 ...oke-IdleStepTriggerDirectorySync.Tests.ps1 |  2 +-
 tests/Steps/_testHelpers.Steps.ps1            | 62 +++++++++++++++++++
 tests/_testHelpers.ps1                        | 53 ++--------------
 32 files changed, 113 insertions(+), 79 deletions(-)
 rename tests/{ => Core}/CapabilityDeprecation.Tests.ps1 (98%)
 rename tests/{ => Core}/Copy-IdleRedactedObject.Tests.ps1 (97%)
 rename tests/{ => Core}/Export-IdlePlan.Tests.ps1 (98%)
 rename tests/{ => Core}/Get-IdleProviderCapabilities.Tests.ps1 (98%)
 rename tests/{ => Core}/ImportIdLE.Tests.ps1 (95%)
 rename tests/{ => Core}/Invoke-IdlePlan.Condition.Tests.ps1 (97%)
 rename tests/{ => Core}/Invoke-IdlePlan.ExecutionOptions.Tests.ps1 (99%)
 rename tests/{ => Core}/Invoke-IdlePlan.Retry.Tests.ps1 (97%)
 rename tests/{ => Core}/Invoke-IdlePlan.StepRegistry.Tests.ps1 (95%)
 rename tests/{ => Core}/Invoke-IdlePlan.Tests.ps1 (99%)
 rename tests/{ => Core}/New-IdleLifecycleRequest.Tests.ps1 (98%)
 rename tests/{ => Core}/New-IdlePlan.Capabilities.Tests.ps1 (99%)
 rename tests/{ => Core}/New-IdlePlan.Tests.ps1 (98%)
 rename tests/{ => Core}/Redaction.Boundaries.Tests.ps1 (98%)
 rename tests/{ => Core}/Resolve-IdleStepMetadataCatalog.Tests.ps1 (99%)
 rename tests/{ => Core}/Resolve-IdleWorkflowTemplates.Tests.ps1 (99%)
 rename tests/{ => Core}/Test-IdleCondition.Tests.ps1 (99%)
 rename tests/{ => Core}/Test-IdleWorkflow.Tests.ps1 (97%)
 rename tests/{ => Examples}/WorkflowSamples.Tests.ps1 (97%)
 rename tests/{ => Packaging}/ModuleManifests.Tests.ps1 (83%)
 rename tests/{ => Packaging}/ModuleSurface.Tests.ps1 (99%)
 rename tests/{ => Packaging}/New-IdleReleaseArtifact.Tests.ps1 (98%)
 rename tests/{ => Packaging}/PublicApi.Tests.ps1 (94%)
 create mode 100644 tests/Providers/_testHelpers.Providers.ps1
 rename tests/{ => Steps}/Invoke-IdleStepAuthSession.Tests.ps1 (100%)
 rename tests/{ => Steps}/Invoke-IdleStepEnsureEntitlement.Tests.ps1 (97%)
 rename tests/{ => Steps}/Invoke-IdleStepMailboxGetInfo.Tests.ps1 (98%)
 rename tests/{ => Steps}/Invoke-IdleStepMailboxOutOfOfficeEnsure.Tests.ps1 (99%)
 rename tests/{ => Steps}/Invoke-IdleStepMailboxTypeEnsure.Tests.ps1 (98%)
 rename tests/{ => Steps}/Invoke-IdleStepTriggerDirectorySync.Tests.ps1 (99%)
 create mode 100644 tests/Steps/_testHelpers.Steps.ps1

diff --git a/tests/CapabilityDeprecation.Tests.ps1 b/tests/Core/CapabilityDeprecation.Tests.ps1
similarity index 98%
rename from tests/CapabilityDeprecation.Tests.ps1
rename to tests/Core/CapabilityDeprecation.Tests.ps1
index 263cc27d..927a9023 100644
--- a/tests/CapabilityDeprecation.Tests.ps1
+++ b/tests/Core/CapabilityDeprecation.Tests.ps1
@@ -1,7 +1,7 @@
 Set-StrictMode -Version Latest
 
 BeforeAll {
-    . (Join-Path $PSScriptRoot '_testHelpers.ps1')
+    . (Join-Path (Split-Path -Path $PSScriptRoot -Parent) '_testHelpers.ps1')
     Import-IdleTestModule
     
     # Import mailbox steps module for capability metadata
diff --git a/tests/Copy-IdleRedactedObject.Tests.ps1 b/tests/Core/Copy-IdleRedactedObject.Tests.ps1
similarity index 97%
rename from tests/Copy-IdleRedactedObject.Tests.ps1
rename to tests/Core/Copy-IdleRedactedObject.Tests.ps1
index a9ee74c7..b124a588 100644
--- a/tests/Copy-IdleRedactedObject.Tests.ps1
+++ b/tests/Core/Copy-IdleRedactedObject.Tests.ps1
@@ -1,5 +1,5 @@
 BeforeDiscovery {
-    . (Join-Path $PSScriptRoot '_testHelpers.ps1')
+    . (Join-Path (Split-Path -Path $PSScriptRoot -Parent) '_testHelpers.ps1')
     Import-IdleTestModule
 }
 
diff --git a/tests/Export-IdlePlan.Tests.ps1 b/tests/Core/Export-IdlePlan.Tests.ps1
similarity index 98%
rename from tests/Export-IdlePlan.Tests.ps1
rename to tests/Core/Export-IdlePlan.Tests.ps1
index d8bc5c52..f16e300d 100644
--- a/tests/Export-IdlePlan.Tests.ps1
+++ b/tests/Core/Export-IdlePlan.Tests.ps1
@@ -2,7 +2,7 @@
 Set-StrictMode -Version Latest
 
 BeforeAll {
-    . (Join-Path $PSScriptRoot '_testHelpers.ps1')
+    . (Join-Path (Split-Path -Path $PSScriptRoot -Parent) '_testHelpers.ps1')
     Import-IdleTestModule
 }
 
diff --git a/tests/Get-IdleProviderCapabilities.Tests.ps1 b/tests/Core/Get-IdleProviderCapabilities.Tests.ps1
similarity index 98%
rename from tests/Get-IdleProviderCapabilities.Tests.ps1
rename to tests/Core/Get-IdleProviderCapabilities.Tests.ps1
index 0f68fc0d..3c995126 100644
--- a/tests/Get-IdleProviderCapabilities.Tests.ps1
+++ b/tests/Core/Get-IdleProviderCapabilities.Tests.ps1
@@ -1,7 +1,7 @@
 Set-StrictMode -Version Latest
 
 BeforeDiscovery {
-    . (Join-Path $PSScriptRoot '_testHelpers.ps1')
+    . (Join-Path (Split-Path -Path $PSScriptRoot -Parent) '_testHelpers.ps1')
     Import-IdleTestModule
 }
 
diff --git a/tests/ImportIdLE.Tests.ps1 b/tests/Core/ImportIdLE.Tests.ps1
similarity index 95%
rename from tests/ImportIdLE.Tests.ps1
rename to tests/Core/ImportIdLE.Tests.ps1
index ae6439e8..ff356908 100644
--- a/tests/ImportIdLE.Tests.ps1
+++ b/tests/Core/ImportIdLE.Tests.ps1
@@ -1,7 +1,7 @@
 Set-StrictMode -Version Latest
 
 BeforeAll {
-    . (Join-Path $PSScriptRoot '_testHelpers.ps1')
+    . (Join-Path (Split-Path -Path $PSScriptRoot -Parent) '_testHelpers.ps1')
     $repoRoot = Get-RepoRootPath
     $importScript = Join-Path -Path $repoRoot -ChildPath 'tools/import-idle.ps1'
 }
diff --git a/tests/Invoke-IdlePlan.Condition.Tests.ps1 b/tests/Core/Invoke-IdlePlan.Condition.Tests.ps1
similarity index 97%
rename from tests/Invoke-IdlePlan.Condition.Tests.ps1
rename to tests/Core/Invoke-IdlePlan.Condition.Tests.ps1
index d2a08229..e2ded0c5 100644
--- a/tests/Invoke-IdlePlan.Condition.Tests.ps1
+++ b/tests/Core/Invoke-IdlePlan.Condition.Tests.ps1
@@ -1,5 +1,5 @@
 BeforeDiscovery {
-    . (Join-Path $PSScriptRoot '_testHelpers.ps1')
+    . (Join-Path (Split-Path -Path $PSScriptRoot -Parent) '_testHelpers.ps1')
     Import-IdleTestModule
 }
 
diff --git a/tests/Invoke-IdlePlan.ExecutionOptions.Tests.ps1 b/tests/Core/Invoke-IdlePlan.ExecutionOptions.Tests.ps1
similarity index 99%
rename from tests/Invoke-IdlePlan.ExecutionOptions.Tests.ps1
rename to tests/Core/Invoke-IdlePlan.ExecutionOptions.Tests.ps1
index fef30cfd..2a59f2d0 100644
--- a/tests/Invoke-IdlePlan.ExecutionOptions.Tests.ps1
+++ b/tests/Core/Invoke-IdlePlan.ExecutionOptions.Tests.ps1
@@ -1,10 +1,10 @@
 BeforeDiscovery {
-    . (Join-Path $PSScriptRoot '_testHelpers.ps1')
+    . (Join-Path (Split-Path -Path $PSScriptRoot -Parent) '_testHelpers.ps1')
     Import-IdleTestModule
 }
 
 BeforeAll {
-    . (Join-Path $PSScriptRoot '_testHelpers.ps1')
+    . (Join-Path (Split-Path -Path $PSScriptRoot -Parent) '_testHelpers.ps1')
     Import-IdleTestModule
 
     # Create a dedicated test module for retry profile testing
diff --git a/tests/Invoke-IdlePlan.Retry.Tests.ps1 b/tests/Core/Invoke-IdlePlan.Retry.Tests.ps1
similarity index 97%
rename from tests/Invoke-IdlePlan.Retry.Tests.ps1
rename to tests/Core/Invoke-IdlePlan.Retry.Tests.ps1
index 229e70e5..7eaa5cf2 100644
--- a/tests/Invoke-IdlePlan.Retry.Tests.ps1
+++ b/tests/Core/Invoke-IdlePlan.Retry.Tests.ps1
@@ -1,10 +1,10 @@
 BeforeDiscovery {
-    . (Join-Path $PSScriptRoot '_testHelpers.ps1')
+    . (Join-Path (Split-Path -Path $PSScriptRoot -Parent) '_testHelpers.ps1')
     Import-IdleTestModule
 }
 
 BeforeAll {
-    . (Join-Path $PSScriptRoot '_testHelpers.ps1')
+    . (Join-Path (Split-Path -Path $PSScriptRoot -Parent) '_testHelpers.ps1')
     Import-IdleTestModule
     
     # Create a dedicated, ephemeral test module that exports the step handlers.
diff --git a/tests/Invoke-IdlePlan.StepRegistry.Tests.ps1 b/tests/Core/Invoke-IdlePlan.StepRegistry.Tests.ps1
similarity index 95%
rename from tests/Invoke-IdlePlan.StepRegistry.Tests.ps1
rename to tests/Core/Invoke-IdlePlan.StepRegistry.Tests.ps1
index 3962ca03..e219767e 100644
--- a/tests/Invoke-IdlePlan.StepRegistry.Tests.ps1
+++ b/tests/Core/Invoke-IdlePlan.StepRegistry.Tests.ps1
@@ -1,5 +1,5 @@
 BeforeAll {
-    . (Join-Path $PSScriptRoot '_testHelpers.ps1')
+    . (Join-Path (Split-Path -Path $PSScriptRoot -Parent) '_testHelpers.ps1')
     Import-IdleTestModule
 
     # The meta module (IdLE) does not automatically import optional step packs.
diff --git a/tests/Invoke-IdlePlan.Tests.ps1 b/tests/Core/Invoke-IdlePlan.Tests.ps1
similarity index 99%
rename from tests/Invoke-IdlePlan.Tests.ps1
rename to tests/Core/Invoke-IdlePlan.Tests.ps1
index dab5cf41..17bef20b 100644
--- a/tests/Invoke-IdlePlan.Tests.ps1
+++ b/tests/Core/Invoke-IdlePlan.Tests.ps1
@@ -1,5 +1,5 @@
 BeforeAll {
-    . (Join-Path $PSScriptRoot '_testHelpers.ps1')
+    . (Join-Path (Split-Path -Path $PSScriptRoot -Parent) '_testHelpers.ps1')
     Import-IdleTestModule
 
     # The engine invokes step handlers by function name (string) inside module scope.
diff --git a/tests/New-IdleLifecycleRequest.Tests.ps1 b/tests/Core/New-IdleLifecycleRequest.Tests.ps1
similarity index 98%
rename from tests/New-IdleLifecycleRequest.Tests.ps1
rename to tests/Core/New-IdleLifecycleRequest.Tests.ps1
index 06901ef0..e20982fe 100644
--- a/tests/New-IdleLifecycleRequest.Tests.ps1
+++ b/tests/Core/New-IdleLifecycleRequest.Tests.ps1
@@ -1,5 +1,5 @@
 BeforeAll {
-    . (Join-Path $PSScriptRoot '_testHelpers.ps1')
+    . (Join-Path (Split-Path -Path $PSScriptRoot -Parent) '_testHelpers.ps1')
     Import-IdleTestModule
 }
 
diff --git a/tests/New-IdlePlan.Capabilities.Tests.ps1 b/tests/Core/New-IdlePlan.Capabilities.Tests.ps1
similarity index 99%
rename from tests/New-IdlePlan.Capabilities.Tests.ps1
rename to tests/Core/New-IdlePlan.Capabilities.Tests.ps1
index e28ac11f..ef898aff 100644
--- a/tests/New-IdlePlan.Capabilities.Tests.ps1
+++ b/tests/Core/New-IdlePlan.Capabilities.Tests.ps1
@@ -1,5 +1,5 @@
 BeforeAll {
-    . (Join-Path $PSScriptRoot '_testHelpers.ps1')
+    . (Join-Path (Split-Path -Path $PSScriptRoot -Parent) '_testHelpers.ps1')
     Import-IdleTestModule
     $fixturesPath = Join-Path $PSScriptRoot 'fixtures/workflows'
 }
diff --git a/tests/New-IdlePlan.Tests.ps1 b/tests/Core/New-IdlePlan.Tests.ps1
similarity index 98%
rename from tests/New-IdlePlan.Tests.ps1
rename to tests/Core/New-IdlePlan.Tests.ps1
index 66c27ef2..bc0c7b2a 100644
--- a/tests/New-IdlePlan.Tests.ps1
+++ b/tests/Core/New-IdlePlan.Tests.ps1
@@ -1,5 +1,5 @@
 BeforeAll {
-    . (Join-Path $PSScriptRoot '_testHelpers.ps1')
+    . (Join-Path (Split-Path -Path $PSScriptRoot -Parent) '_testHelpers.ps1')
     Import-IdleTestModule
 }
 
diff --git a/tests/Redaction.Boundaries.Tests.ps1 b/tests/Core/Redaction.Boundaries.Tests.ps1
similarity index 98%
rename from tests/Redaction.Boundaries.Tests.ps1
rename to tests/Core/Redaction.Boundaries.Tests.ps1
index 45018d47..a77e39e5 100644
--- a/tests/Redaction.Boundaries.Tests.ps1
+++ b/tests/Core/Redaction.Boundaries.Tests.ps1
@@ -1,5 +1,5 @@
 BeforeDiscovery {
-    . (Join-Path $PSScriptRoot '_testHelpers.ps1')
+    . (Join-Path (Split-Path -Path $PSScriptRoot -Parent) '_testHelpers.ps1')
     Import-IdleTestModule
 }
 
diff --git a/tests/Resolve-IdleStepMetadataCatalog.Tests.ps1 b/tests/Core/Resolve-IdleStepMetadataCatalog.Tests.ps1
similarity index 99%
rename from tests/Resolve-IdleStepMetadataCatalog.Tests.ps1
rename to tests/Core/Resolve-IdleStepMetadataCatalog.Tests.ps1
index 9c6cff7e..ed0fe75e 100644
--- a/tests/Resolve-IdleStepMetadataCatalog.Tests.ps1
+++ b/tests/Core/Resolve-IdleStepMetadataCatalog.Tests.ps1
@@ -1,5 +1,5 @@
 BeforeAll {
-    . (Join-Path $PSScriptRoot '_testHelpers.ps1')
+    . (Join-Path (Split-Path -Path $PSScriptRoot -Parent) '_testHelpers.ps1')
     Import-IdleTestModule
     $fixturesPath = Join-Path $PSScriptRoot 'fixtures/workflows'
 }
diff --git a/tests/Resolve-IdleWorkflowTemplates.Tests.ps1 b/tests/Core/Resolve-IdleWorkflowTemplates.Tests.ps1
similarity index 99%
rename from tests/Resolve-IdleWorkflowTemplates.Tests.ps1
rename to tests/Core/Resolve-IdleWorkflowTemplates.Tests.ps1
index 6a3ff40b..72895253 100644
--- a/tests/Resolve-IdleWorkflowTemplates.Tests.ps1
+++ b/tests/Core/Resolve-IdleWorkflowTemplates.Tests.ps1
@@ -1,5 +1,5 @@
 BeforeAll {
-    . (Join-Path $PSScriptRoot '_testHelpers.ps1')
+    . (Join-Path (Split-Path -Path $PSScriptRoot -Parent) '_testHelpers.ps1')
     Import-IdleTestModule
     
     # Helper to get fixture workflow path
diff --git a/tests/Test-IdleCondition.Tests.ps1 b/tests/Core/Test-IdleCondition.Tests.ps1
similarity index 99%
rename from tests/Test-IdleCondition.Tests.ps1
rename to tests/Core/Test-IdleCondition.Tests.ps1
index 86dfd1d7..6d173597 100644
--- a/tests/Test-IdleCondition.Tests.ps1
+++ b/tests/Core/Test-IdleCondition.Tests.ps1
@@ -1,5 +1,5 @@
 BeforeDiscovery {
-    . (Join-Path $PSScriptRoot '_testHelpers.ps1')
+    . (Join-Path (Split-Path -Path $PSScriptRoot -Parent) '_testHelpers.ps1')
     Import-IdleTestModule
 }
 
diff --git a/tests/Test-IdleWorkflow.Tests.ps1 b/tests/Core/Test-IdleWorkflow.Tests.ps1
similarity index 97%
rename from tests/Test-IdleWorkflow.Tests.ps1
rename to tests/Core/Test-IdleWorkflow.Tests.ps1
index 6bb6733e..44ab4881 100644
--- a/tests/Test-IdleWorkflow.Tests.ps1
+++ b/tests/Core/Test-IdleWorkflow.Tests.ps1
@@ -1,5 +1,5 @@
 BeforeAll {
-    . (Join-Path $PSScriptRoot '_testHelpers.ps1')
+    . (Join-Path (Split-Path -Path $PSScriptRoot -Parent) '_testHelpers.ps1')
     Import-IdleTestModule
 }
 
diff --git a/tests/WorkflowSamples.Tests.ps1 b/tests/Examples/WorkflowSamples.Tests.ps1
similarity index 97%
rename from tests/WorkflowSamples.Tests.ps1
rename to tests/Examples/WorkflowSamples.Tests.ps1
index 24f7eec8..d3ad0bbc 100644
--- a/tests/WorkflowSamples.Tests.ps1
+++ b/tests/Examples/WorkflowSamples.Tests.ps1
@@ -1,7 +1,7 @@
 Set-StrictMode -Version Latest
 
 BeforeAll {
-    . (Join-Path $PSScriptRoot '_testHelpers.ps1')
+    . (Join-Path (Split-Path -Path $PSScriptRoot -Parent) '_testHelpers.ps1')
     Import-IdleTestModule
 
     $workflowsPath = Join-Path -Path (Get-RepoRootPath) -ChildPath 'examples/workflows'
diff --git a/tests/ModuleManifests.Tests.ps1 b/tests/Packaging/ModuleManifests.Tests.ps1
similarity index 83%
rename from tests/ModuleManifests.Tests.ps1
rename to tests/Packaging/ModuleManifests.Tests.ps1
index 029253ec..b41905a7 100644
--- a/tests/ModuleManifests.Tests.ps1
+++ b/tests/Packaging/ModuleManifests.Tests.ps1
@@ -1,7 +1,7 @@
 Set-StrictMode -Version Latest
 
 BeforeAll {
-    . (Join-Path $PSScriptRoot '_testHelpers.ps1')
+    . (Join-Path (Split-Path -Path $PSScriptRoot -Parent) '_testHelpers.ps1')
     Import-IdleTestModule
 }
 
diff --git a/tests/ModuleSurface.Tests.ps1 b/tests/Packaging/ModuleSurface.Tests.ps1
similarity index 99%
rename from tests/ModuleSurface.Tests.ps1
rename to tests/Packaging/ModuleSurface.Tests.ps1
index 94473ea1..57c9ddad 100644
--- a/tests/ModuleSurface.Tests.ps1
+++ b/tests/Packaging/ModuleSurface.Tests.ps1
@@ -5,7 +5,7 @@ BeforeAll {
     $stepsPsd1 = Join-Path $repoRoot 'src\IdLE.Steps.Common\IdLE.Steps.Common.psd1'
     $providerMockPsd1 = Join-Path $repoRoot 'src\IdLE.Provider.Mock\IdLE.Provider.Mock.psd1'
 
-    . (Join-Path $PSScriptRoot '_testHelpers.ps1')
+    . (Join-Path (Split-Path -Path $PSScriptRoot -Parent) '_testHelpers.ps1')
     Import-IdleTestModule
 
     # The engine invokes step handlers by function name (string).
diff --git a/tests/New-IdleReleaseArtifact.Tests.ps1 b/tests/Packaging/New-IdleReleaseArtifact.Tests.ps1
similarity index 98%
rename from tests/New-IdleReleaseArtifact.Tests.ps1
rename to tests/Packaging/New-IdleReleaseArtifact.Tests.ps1
index c7c40e8f..bca6bdb9 100644
--- a/tests/New-IdleReleaseArtifact.Tests.ps1
+++ b/tests/Packaging/New-IdleReleaseArtifact.Tests.ps1
@@ -2,7 +2,7 @@
 Set-StrictMode -Version Latest
 
 BeforeAll {
-    . (Join-Path $PSScriptRoot '_testHelpers.ps1')
+    . (Join-Path (Split-Path -Path $PSScriptRoot -Parent) '_testHelpers.ps1')
 
     $script:RepoRoot = Get-RepoRootPath
     $script:ReleaseScriptPath = Join-Path $script:RepoRoot 'tools/New-IdleReleaseArtifact.ps1'
diff --git a/tests/PublicApi.Tests.ps1 b/tests/Packaging/PublicApi.Tests.ps1
similarity index 94%
rename from tests/PublicApi.Tests.ps1
rename to tests/Packaging/PublicApi.Tests.ps1
index be225b1f..d4c94c28 100644
--- a/tests/PublicApi.Tests.ps1
+++ b/tests/Packaging/PublicApi.Tests.ps1
@@ -1,7 +1,7 @@
 Set-StrictMode -Version Latest
 
 BeforeAll {
-    . (Join-Path $PSScriptRoot '_testHelpers.ps1')
+    . (Join-Path (Split-Path -Path $PSScriptRoot -Parent) '_testHelpers.ps1')
     Import-IdleTestModule
 }
 
diff --git a/tests/Providers/_testHelpers.Providers.ps1 b/tests/Providers/_testHelpers.Providers.ps1
new file mode 100644
index 00000000..58fe7df3
--- /dev/null
+++ b/tests/Providers/_testHelpers.Providers.ps1
@@ -0,0 +1,17 @@
+Set-StrictMode -Version Latest
+
+<#
+.SYNOPSIS
+Provider-specific test helpers for IdLE tests.
+
+.DESCRIPTION
+This file contains helper functions, fixtures, and test doubles specifically
+related to provider testing.
+
+This file is sourced by tests/_testHelpers.ps1 and should not be dot-sourced
+directly by test files.
+#>
+
+# Provider-specific helpers will be added here as needed.
+# This file is currently empty but provides a clear extension point for
+# provider-related test infrastructure.
diff --git a/tests/Invoke-IdleStepAuthSession.Tests.ps1 b/tests/Steps/Invoke-IdleStepAuthSession.Tests.ps1
similarity index 100%
rename from tests/Invoke-IdleStepAuthSession.Tests.ps1
rename to tests/Steps/Invoke-IdleStepAuthSession.Tests.ps1
diff --git a/tests/Invoke-IdleStepEnsureEntitlement.Tests.ps1 b/tests/Steps/Invoke-IdleStepEnsureEntitlement.Tests.ps1
similarity index 97%
rename from tests/Invoke-IdleStepEnsureEntitlement.Tests.ps1
rename to tests/Steps/Invoke-IdleStepEnsureEntitlement.Tests.ps1
index c6e6e9e2..c0baee72 100644
--- a/tests/Invoke-IdleStepEnsureEntitlement.Tests.ps1
+++ b/tests/Steps/Invoke-IdleStepEnsureEntitlement.Tests.ps1
@@ -1,7 +1,7 @@
 Set-StrictMode -Version Latest
 
 BeforeAll {
-    . (Join-Path $PSScriptRoot '_testHelpers.ps1')
+    . (Join-Path (Split-Path -Path $PSScriptRoot -Parent) '_testHelpers.ps1')
     Import-IdleTestModule
 }
 
diff --git a/tests/Invoke-IdleStepMailboxGetInfo.Tests.ps1 b/tests/Steps/Invoke-IdleStepMailboxGetInfo.Tests.ps1
similarity index 98%
rename from tests/Invoke-IdleStepMailboxGetInfo.Tests.ps1
rename to tests/Steps/Invoke-IdleStepMailboxGetInfo.Tests.ps1
index b38e7955..5845ad6a 100644
--- a/tests/Invoke-IdleStepMailboxGetInfo.Tests.ps1
+++ b/tests/Steps/Invoke-IdleStepMailboxGetInfo.Tests.ps1
@@ -1,7 +1,7 @@
 Set-StrictMode -Version Latest
 
 BeforeAll {
-    . (Join-Path $PSScriptRoot '_testHelpers.ps1')
+    . (Join-Path (Split-Path -Path $PSScriptRoot -Parent) '_testHelpers.ps1')
     Import-IdleTestModule
     
     # Import Mailbox step pack
diff --git a/tests/Invoke-IdleStepMailboxOutOfOfficeEnsure.Tests.ps1 b/tests/Steps/Invoke-IdleStepMailboxOutOfOfficeEnsure.Tests.ps1
similarity index 99%
rename from tests/Invoke-IdleStepMailboxOutOfOfficeEnsure.Tests.ps1
rename to tests/Steps/Invoke-IdleStepMailboxOutOfOfficeEnsure.Tests.ps1
index 2717a799..2da6c0fb 100644
--- a/tests/Invoke-IdleStepMailboxOutOfOfficeEnsure.Tests.ps1
+++ b/tests/Steps/Invoke-IdleStepMailboxOutOfOfficeEnsure.Tests.ps1
@@ -1,7 +1,7 @@
 Set-StrictMode -Version Latest
 
 BeforeAll {
-    . (Join-Path $PSScriptRoot '_testHelpers.ps1')
+    . (Join-Path (Split-Path -Path $PSScriptRoot -Parent) '_testHelpers.ps1')
     Import-IdleTestModule
     
     # Import Mailbox step pack
diff --git a/tests/Invoke-IdleStepMailboxTypeEnsure.Tests.ps1 b/tests/Steps/Invoke-IdleStepMailboxTypeEnsure.Tests.ps1
similarity index 98%
rename from tests/Invoke-IdleStepMailboxTypeEnsure.Tests.ps1
rename to tests/Steps/Invoke-IdleStepMailboxTypeEnsure.Tests.ps1
index 2535dc95..5fdf1c85 100644
--- a/tests/Invoke-IdleStepMailboxTypeEnsure.Tests.ps1
+++ b/tests/Steps/Invoke-IdleStepMailboxTypeEnsure.Tests.ps1
@@ -1,7 +1,7 @@
 Set-StrictMode -Version Latest
 
 BeforeAll {
-    . (Join-Path $PSScriptRoot '_testHelpers.ps1')
+    . (Join-Path (Split-Path -Path $PSScriptRoot -Parent) '_testHelpers.ps1')
     Import-IdleTestModule
     
     # Import Mailbox step pack
diff --git a/tests/Invoke-IdleStepTriggerDirectorySync.Tests.ps1 b/tests/Steps/Invoke-IdleStepTriggerDirectorySync.Tests.ps1
similarity index 99%
rename from tests/Invoke-IdleStepTriggerDirectorySync.Tests.ps1
rename to tests/Steps/Invoke-IdleStepTriggerDirectorySync.Tests.ps1
index 82015d90..d2629c89 100644
--- a/tests/Invoke-IdleStepTriggerDirectorySync.Tests.ps1
+++ b/tests/Steps/Invoke-IdleStepTriggerDirectorySync.Tests.ps1
@@ -1,7 +1,7 @@
 Set-StrictMode -Version Latest
 
 BeforeAll {
-    . (Join-Path $PSScriptRoot '_testHelpers.ps1')
+    . (Join-Path (Split-Path -Path $PSScriptRoot -Parent) '_testHelpers.ps1')
     Import-IdleTestModule
 }
 
diff --git a/tests/Steps/_testHelpers.Steps.ps1 b/tests/Steps/_testHelpers.Steps.ps1
new file mode 100644
index 00000000..1ab500e2
--- /dev/null
+++ b/tests/Steps/_testHelpers.Steps.ps1
@@ -0,0 +1,62 @@
+Set-StrictMode -Version Latest
+
+<#
+.SYNOPSIS
+Step-specific test helpers for IdLE tests.
+
+.DESCRIPTION
+This file contains helper functions, fixtures, and test doubles specifically
+related to step testing.
+
+This file is sourced by tests/_testHelpers.ps1 and should not be dot-sourced
+directly by test files.
+#>
+
+function New-IdleTestStepMetadata {
+    <#
+    .SYNOPSIS
+    Creates test step metadata for custom step types used in tests.
+
+    .DESCRIPTION
+    Helper function to create StepMetadata entries for test-specific step types.
+    By default, creates metadata with no required capabilities.
+
+    .PARAMETER StepTypes
+    Array of step type names to create metadata for.
+
+    .PARAMETER RequiredCapabilities
+    Hashtable mapping step types to their required capabilities.
+
+    .EXAMPLE
+    $metadata = New-IdleTestStepMetadata -StepTypes @('IdLE.Step.ResolveIdentity', 'IdLE.Step.Primary')
+
+    .EXAMPLE
+    $metadata = New-IdleTestStepMetadata -StepTypes @('IdLE.Step.Custom') -RequiredCapabilities @{
+        'IdLE.Step.Custom' = @('Custom.Capability')
+    }
+    #>
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)]
+        [string[]] $StepTypes,
+
+        [Parameter()]
+        [hashtable] $RequiredCapabilities = @{}
+    )
+
+    $metadata = @{}
+    foreach ($stepType in $StepTypes) {
+        $caps = if ($RequiredCapabilities.ContainsKey($stepType)) {
+            $RequiredCapabilities[$stepType]
+        }
+        else {
+            @()
+        }
+        
+        $metadata[$stepType] = @{
+            RequiredCapabilities = $caps
+        }
+    }
+
+    return $metadata
+}
diff --git a/tests/_testHelpers.ps1 b/tests/_testHelpers.ps1
index f3f3ed95..2653ea58 100644
--- a/tests/_testHelpers.ps1
+++ b/tests/_testHelpers.ps1
@@ -1,5 +1,9 @@
 Set-StrictMode -Version Latest
 
+# Dot-source domain-specific test helpers
+. (Join-Path -Path $PSScriptRoot -ChildPath 'Steps/_testHelpers.Steps.ps1')
+. (Join-Path -Path $PSScriptRoot -ChildPath 'Providers/_testHelpers.Providers.ps1')
+
 function Get-RepoRootPath {
     [CmdletBinding()]
     param()
@@ -50,52 +54,3 @@ function Get-ModuleManifestPaths {
         Select-Object -ExpandProperty FullName
 }
 
-function New-IdleTestStepMetadata {
-    <#
-    .SYNOPSIS
-    Creates test step metadata for custom step types used in tests.
-
-    .DESCRIPTION
-    Helper function to create StepMetadata entries for test-specific step types.
-    By default, creates metadata with no required capabilities.
-
-    .PARAMETER StepTypes
-    Array of step type names to create metadata for.
-
-    .PARAMETER RequiredCapabilities
-    Hashtable mapping step types to their required capabilities.
-
-    .EXAMPLE
-    $metadata = New-IdleTestStepMetadata -StepTypes @('IdLE.Step.ResolveIdentity', 'IdLE.Step.Primary')
-
-    .EXAMPLE
-    $metadata = New-IdleTestStepMetadata -StepTypes @('IdLE.Step.Custom') -RequiredCapabilities @{
-        'IdLE.Step.Custom' = @('Custom.Capability')
-    }
-    #>
-    [CmdletBinding()]
-    param(
-        [Parameter(Mandatory)]
-        [string[]] $StepTypes,
-
-        [Parameter()]
-        [hashtable] $RequiredCapabilities = @{}
-    )
-
-    $metadata = @{}
-    foreach ($stepType in $StepTypes) {
-        $caps = if ($RequiredCapabilities.ContainsKey($stepType)) {
-            $RequiredCapabilities[$stepType]
-        }
-        else {
-            @()
-        }
-        
-        $metadata[$stepType] = @{
-            RequiredCapabilities = $caps
-        }
-    }
-
-    return $metadata
-}
-

From 80e144fdb85dc7282b018d263fd7658f770a30bc Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Mon, 26 Jan 2026 06:47:43 +0000
Subject: [PATCH 3/5] Fix test helper imports and relative paths after
 restructure

- Add missing IdLE.Steps.Mailbox module import to test helpers
- Fix relative paths in Invoke-IdleStepAuthSession.Tests.ps1 (BeforeAll imports)
- Fix relative paths in CapabilityDeprecation.Tests.ps1 (examples/workflows references)
- Fix relative paths in ModuleSurface.Tests.ps1 (repoRoot calculation)
- Tests now at 287 passed / 46 failed (was 247 passed / 87 failed)

Co-authored-by: blindzero <13959569+blindzero@users.noreply.github.com>
---
 tests/Core/CapabilityDeprecation.Tests.ps1       | 6 +++---
 tests/Packaging/ModuleSurface.Tests.ps1          | 2 +-
 tests/Steps/Invoke-IdleStepAuthSession.Tests.ps1 | 6 +++---
 tests/_testHelpers.ps1                           | 3 +++
 4 files changed, 10 insertions(+), 7 deletions(-)

diff --git a/tests/Core/CapabilityDeprecation.Tests.ps1 b/tests/Core/CapabilityDeprecation.Tests.ps1
index 927a9023..43fbf0b9 100644
--- a/tests/Core/CapabilityDeprecation.Tests.ps1
+++ b/tests/Core/CapabilityDeprecation.Tests.ps1
@@ -5,7 +5,7 @@ BeforeAll {
     Import-IdleTestModule
     
     # Import mailbox steps module for capability metadata
-    $mailboxStepsPath = Join-Path $PSScriptRoot '..' 'src' 'IdLE.Steps.Mailbox' 'IdLE.Steps.Mailbox.psd1'
+    $mailboxStepsPath = Join-Path $PSScriptRoot '..' '..' 'src' 'IdLE.Steps.Mailbox' 'IdLE.Steps.Mailbox.psd1'
     if (Test-Path $mailboxStepsPath) {
         Import-Module $mailboxStepsPath -Force -ErrorAction SilentlyContinue
     }
@@ -27,7 +27,7 @@ Describe 'Capability Deprecation and Migration' {
             }
 
             # Use a real workflow file that uses mailbox steps
-            $wfPath = Join-Path $PSScriptRoot '..' 'examples' 'workflows' 'live' 'exo-leaver-mailbox-offboarding.psd1'
+            $wfPath = Join-Path $PSScriptRoot '..' '..' 'examples' 'workflows' 'live' 'exo-leaver-mailbox-offboarding.psd1'
             
             # Verify the workflow file exists
             $wfPath | Should -Exist
@@ -65,7 +65,7 @@ Describe 'Capability Deprecation and Migration' {
             }
 
             # Use a real workflow file
-            $wfPath = Join-Path $PSScriptRoot '..' 'examples' 'workflows' 'live' 'exo-leaver-mailbox-offboarding.psd1'
+            $wfPath = Join-Path $PSScriptRoot '..' '..' 'examples' 'workflows' 'live' 'exo-leaver-mailbox-offboarding.psd1'
             
             $req = New-IdleLifecycleRequest -LifecycleEvent 'Leaver'
             $providers = @{ MockProvider = $mockProvider }
diff --git a/tests/Packaging/ModuleSurface.Tests.ps1 b/tests/Packaging/ModuleSurface.Tests.ps1
index 57c9ddad..2ee12ba2 100644
--- a/tests/Packaging/ModuleSurface.Tests.ps1
+++ b/tests/Packaging/ModuleSurface.Tests.ps1
@@ -1,5 +1,5 @@
 BeforeAll {
-    $repoRoot = Resolve-Path (Join-Path $PSScriptRoot '..')
+    $repoRoot = Resolve-Path (Join-Path $PSScriptRoot '..' '..')
     $idlePsd1 = Join-Path $repoRoot 'src\IdLE\IdLE.psd1'
     $corePsd1 = Join-Path $repoRoot 'src\IdLE.Core\IdLE.Core.psd1'
     $stepsPsd1 = Join-Path $repoRoot 'src\IdLE.Steps.Common\IdLE.Steps.Common.psd1'
diff --git a/tests/Steps/Invoke-IdleStepAuthSession.Tests.ps1 b/tests/Steps/Invoke-IdleStepAuthSession.Tests.ps1
index 6d50721d..0640054b 100644
--- a/tests/Steps/Invoke-IdleStepAuthSession.Tests.ps1
+++ b/tests/Steps/Invoke-IdleStepAuthSession.Tests.ps1
@@ -3,9 +3,9 @@
 Describe 'IdLE.Steps - Auth Session Routing' {
 
     BeforeAll {
-        Import-Module -Name (Join-Path -Path $PSScriptRoot -ChildPath '../src/IdLE/IdLE.psd1') -Force
-        Import-Module -Name (Join-Path -Path $PSScriptRoot -ChildPath '../src/IdLE.Core/IdLE.Core.psd1') -Force
-        Import-Module -Name (Join-Path -Path $PSScriptRoot -ChildPath '../src/IdLE.Steps.Common/IdLE.Steps.Common.psd1') -Force
+        Import-Module -Name (Join-Path -Path $PSScriptRoot -ChildPath '../../src/IdLE/IdLE.psd1') -Force
+        Import-Module -Name (Join-Path -Path $PSScriptRoot -ChildPath '../../src/IdLE.Core/IdLE.Core.psd1') -Force
+        Import-Module -Name (Join-Path -Path $PSScriptRoot -ChildPath '../../src/IdLE.Steps.Common/IdLE.Steps.Common.psd1') -Force
     }
 
     Context 'EnsureAttribute - Auth Session Acquisition' {
diff --git a/tests/_testHelpers.ps1 b/tests/_testHelpers.ps1
index 2653ea58..b799a2a5 100644
--- a/tests/_testHelpers.ps1
+++ b/tests/_testHelpers.ps1
@@ -38,6 +38,9 @@ function Import-IdleTestModule {
 
     $directorySyncProviderManifestPath = Resolve-Path -Path (Join-Path (Get-RepoRootPath) 'src/IdLE.Provider.DirectorySync.EntraConnect/IdLE.Provider.DirectorySync.EntraConnect.psd1')
     Import-Module -Name $directorySyncProviderManifestPath -Force -ErrorAction Stop
+
+    $stepsMailboxManifestPath = Resolve-Path -Path (Join-Path (Get-RepoRootPath) 'src/IdLE.Steps.Mailbox/IdLE.Steps.Mailbox.psd1')
+    Import-Module -Name $stepsMailboxManifestPath -Force -ErrorAction Stop
 }
 
 function Get-ModuleManifestPaths {

From b89a730db3945cc9805c10b6b0d7197e5e52e832 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Mon, 26 Jan 2026 06:49:52 +0000
Subject: [PATCH 4/5] Fix remaining fixtures path references after restructure

- Fix fixtures paths in New-IdlePlan.Capabilities.Tests.ps1
- Fix fixtures paths in Export-IdlePlan.Tests.ps1
- Fix fixtures paths in Resolve-IdleStepMetadataCatalog.Tests.ps1
- Fix fixtures paths in Resolve-IdleWorkflowTemplates.Tests.ps1
- All tests now passing: 333 passed, 0 failed, 3 skipped
- PSScriptAnalyzer passes with no issues

Co-authored-by: blindzero <13959569+blindzero@users.noreply.github.com>
---
 tests/Core/Export-IdlePlan.Tests.ps1                 | 2 +-
 tests/Core/New-IdlePlan.Capabilities.Tests.ps1       | 2 +-
 tests/Core/Resolve-IdleStepMetadataCatalog.Tests.ps1 | 2 +-
 tests/Core/Resolve-IdleWorkflowTemplates.Tests.ps1   | 2 +-
 4 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/tests/Core/Export-IdlePlan.Tests.ps1 b/tests/Core/Export-IdlePlan.Tests.ps1
index f16e300d..a83ffe78 100644
--- a/tests/Core/Export-IdlePlan.Tests.ps1
+++ b/tests/Core/Export-IdlePlan.Tests.ps1
@@ -48,7 +48,7 @@ Describe 'Export-IdlePlan' {
             
             $plan = New-IdlePlan -WorkflowPath $wfPath -Request $req -Providers $providers
 
-            $expectedPath = Join-Path $PSScriptRoot 'fixtures/plan-export/expected/plan-export.json'
+            $expectedPath = Join-Path $PSScriptRoot '..' 'fixtures/plan-export/expected/plan-export.json'
             $expectedJson = Get-Content -Path $expectedPath -Raw -Encoding utf8
 
             # Act
diff --git a/tests/Core/New-IdlePlan.Capabilities.Tests.ps1 b/tests/Core/New-IdlePlan.Capabilities.Tests.ps1
index ef898aff..b28d11fe 100644
--- a/tests/Core/New-IdlePlan.Capabilities.Tests.ps1
+++ b/tests/Core/New-IdlePlan.Capabilities.Tests.ps1
@@ -1,7 +1,7 @@
 BeforeAll {
     . (Join-Path (Split-Path -Path $PSScriptRoot -Parent) '_testHelpers.ps1')
     Import-IdleTestModule
-    $fixturesPath = Join-Path $PSScriptRoot 'fixtures/workflows'
+    $fixturesPath = Join-Path $PSScriptRoot '..' 'fixtures/workflows'
 }
 
 Describe 'New-IdlePlan - required provider capabilities' {
diff --git a/tests/Core/Resolve-IdleStepMetadataCatalog.Tests.ps1 b/tests/Core/Resolve-IdleStepMetadataCatalog.Tests.ps1
index ed0fe75e..bee647e6 100644
--- a/tests/Core/Resolve-IdleStepMetadataCatalog.Tests.ps1
+++ b/tests/Core/Resolve-IdleStepMetadataCatalog.Tests.ps1
@@ -1,7 +1,7 @@
 BeforeAll {
     . (Join-Path (Split-Path -Path $PSScriptRoot -Parent) '_testHelpers.ps1')
     Import-IdleTestModule
-    $fixturesPath = Join-Path $PSScriptRoot 'fixtures/workflows'
+    $fixturesPath = Join-Path $PSScriptRoot '..' 'fixtures/workflows'
 }
 
 Describe 'Resolve-IdleStepMetadataCatalog - step pack catalog ownership' {
diff --git a/tests/Core/Resolve-IdleWorkflowTemplates.Tests.ps1 b/tests/Core/Resolve-IdleWorkflowTemplates.Tests.ps1
index 72895253..ff371e7f 100644
--- a/tests/Core/Resolve-IdleWorkflowTemplates.Tests.ps1
+++ b/tests/Core/Resolve-IdleWorkflowTemplates.Tests.ps1
@@ -5,7 +5,7 @@ BeforeAll {
     # Helper to get fixture workflow path
     function Get-TemplateTestFixture {
         param([string]$Name)
-        return Join-Path $PSScriptRoot "fixtures/workflows/template-tests/$Name.psd1"
+        return Join-Path $PSScriptRoot ".." "fixtures/workflows/template-tests/$Name.psd1"
     }
 }
 

From 39999babb66081b94508a25cf13f1d4834334f3a Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Mon, 26 Jan 2026 18:50:12 +0000
Subject: [PATCH 5/5] docs: document new test folder structure in testing.md

Add section describing the domain-organized test folder structure:
- Core/, Steps/, Providers/, Packaging/, Examples/ folders
- Test helper organization with single entry point
- Fixture location

This helps contributors understand where to place new tests.

Co-authored-by: blindzero <13959569+blindzero@users.noreply.github.com>
---
 docs/advanced/testing.md | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)

diff --git a/docs/advanced/testing.md b/docs/advanced/testing.md
index 67423d9d..e83f7bb4 100644
--- a/docs/advanced/testing.md
+++ b/docs/advanced/testing.md
@@ -2,6 +2,25 @@
 
 IdLE is designed to be testable in isolation. Tests should be deterministic, fast, and runnable on any machine (local or CI) without requiring live systems.
 
+## Test folder structure
+
+Tests are organized by domain under `tests/`:
+
+- **`tests/Core/`** — Core engine functionality (plan creation, execution, conditions, workflows, capabilities, redaction)
+- **`tests/Steps/`** — Step implementations (built-in steps like EnsureEntitlement, Mailbox operations, DirectorySync)
+- **`tests/Providers/`** — Provider implementations (AD, EntraID, ExchangeOnline, Mock, DirectorySync)
+- **`tests/Packaging/`** — Module manifests, public API surface, release artifacts
+- **`tests/Examples/`** — Workflow samples and demo smoke tests
+- **`tests/fixtures/`** — Test data and workflow definitions for tests
+- **`tests/_testHelpers.ps1`** — Shared test infrastructure (single entry point for all tests)
+
+All test files follow the naming convention `*.Tests.ps1` and are automatically discovered by Pester.
+
+Test helper functions are split by domain:
+- `tests/_testHelpers.ps1` (main entry point, imports domain helpers)
+- `tests/Steps/_testHelpers.Steps.ps1` (step-specific helpers)
+- `tests/Providers/_testHelpers.Providers.ps1` (provider-specific helpers)
+
 ## Running tests locally
 
 Use the canonical test runner: