feat: pass Graph client timeout through Connect-Maester

powershell/public/Connect-Maester.ps1

@@ -84,6 +84,11 @@
 
    Connects using a custom application with client ID f45ec3ad-32f0-4c06-8b69-47682afe0216
 
+.EXAMPLE
+   Connect-Maester -ClientTimeout 900
+
+   Connects to Microsoft Graph with an HTTP client timeout of 900 seconds. This can be useful for long-running tests in large tenants.
+
 .EXAMPLE
    Connect-Maester -Service Graph,SharePointOnline -SharePointClientId '<Client ID>'
 
@@ -140,6 +145,9 @@
       # The Client ID of the app to connect to for Graph. If not specified, the default Graph PowerShell CLI enterprise app will be used. Reference on how to create an enterprise app: https://learn.microsoft.com/powershell/microsoftgraph/authentication-commands?view=graph-powershell-1.0#use-delegated-access-with-a-custom-application-for-microsoft-graph-powershell
       [string]$GraphClientId,
 
+      # The Microsoft Graph HTTP client timeout in seconds. When omitted, the Microsoft Graph PowerShell SDK default is used.
+      [double]$ClientTimeout,
+
       # The Client ID of the PnP Entra ID app for SharePoint Online. Required when Service includes SharePointOnline.
       # Use Register-PnPEntraIDAppForInteractiveLogin to create a dedicated app, or reuse an existing Maester app
       # registration by adding an http://localhost redirect URI and AllSites.FullControl delegated SharePoint permission.
@@ -358,6 +366,9 @@
                if ($TenantId) {
                   $connectParams['TenantId'] = $TenantId
                }
+               if ($PSBoundParameters.ContainsKey('ClientTimeout')) {
+                  $connectParams['ClientTimeout'] = $ClientTimeout
+               }
 
                Write-Verbose "🦒 Connecting to Microsoft Graph with parameters:"
                Write-Verbose ($connectParams | ConvertTo-Json -Depth 5)

powershell/tests/functions/Connect-Maester.Tests.ps1

@@ -40,6 +40,38 @@ Describe 'Connect-Maester' {
         (Get-Command Connect-Maester).Parameters.Keys | Should -Contain 'GitHubOrganization'
     }
 
+    It 'Offers ClientTimeout as a double parameter' {
+        $clientTimeoutParameter = (Get-Command Connect-Maester).Parameters['ClientTimeout']
+
+        $clientTimeoutParameter | Should -Not -BeNullOrEmpty
+        $clientTimeoutParameter.ParameterType | Should -Be ([double])
+    }
+
+    It 'Passes an explicit ClientTimeout to Connect-MgGraph' {
+        Mock Connect-MgGraph -ModuleName Maester {}
+
+        Connect-Maester -ClientTimeout 900
+
+        Should -Invoke Connect-MgGraph -ModuleName Maester -Times 1 -Exactly -ParameterFilter { $ClientTimeout -eq 900 }
+    }
+
+    It 'Does not pass ClientTimeout to Connect-MgGraph when omitted' {
+        Mock Connect-MgGraph -ModuleName Maester {}
+
+        Connect-Maester
+
+        Should -Invoke Connect-MgGraph -ModuleName Maester -Times 1 -Exactly -ParameterFilter { -not $PSBoundParameters.ContainsKey('ClientTimeout') }
+    }
+
+    It 'Does not connect to Graph when ClientTimeout is used with a non-Graph service' {
+        Mock Connect-MgGraph -ModuleName Maester {}
+        Mock Connect-MtGitHub -ModuleName Maester {}
+
+        Connect-Maester -Service GitHub -ClientTimeout 900
+
+        Should -Invoke Connect-MgGraph -ModuleName Maester -Times 0 -Exactly
+    }
+
     It 'Calls Connect-MtGitHub when -Service GitHub is specified' {
         Mock Connect-MtGitHub -ModuleName Maester {}
 

website/docs/faq.md

@@ -25,3 +25,24 @@ Install-Module Pester -MinimumVersion 5.7.1 -MaximumVersion 5.7.1 -Scope Current
 
 To learn more or if you run into Pester installation issues see [Pester Installation and Update](https://pester.dev/docs/introduction/installation)
 
+## Graph requests fail with a timeout error
+
+If a test run fails with an error like `The request was canceled due to the configured HttpClient.Timeout of 300 seconds elapsing`, the Microsoft Graph SDK default timeout has been exceeded.
+
+This is most common when using `-IncludeLongRunning` in tenants with a large number of objects.
+
+When using `Connect-Maester`, pass the timeout to the Microsoft Graph connection:
+
+```powershell
+Connect-Maester -ClientTimeout 900
+Invoke-Maester -IncludeLongRunning
+```
+
+If you connect to Microsoft Graph directly, set the timeout on `Connect-MgGraph` before running Maester:
+
+```powershell
+Connect-MgGraph -Scopes (Get-MtGraphScope) -ClientTimeout 900
+Invoke-Maester -SkipGraphConnect -IncludeLongRunning
+```
+
+When `-ClientTimeout` is omitted, the Microsoft Graph PowerShell SDK default is used. The timeout applies to the Graph connection rather than to an individual test or request.