docs: update run-tests.py documentation with enhanced usage instructions and memory management options (#1250)

…ons and memory management options

# Pull Request Description

## Summary

[Provide a brief description of the changes in this PR]

### Issue Reference

Fixes #[Issue Number]

### Motivation and Context

- Why is this change needed?
- What problem does it solve?
- If it fixes an open issue, please link to the issue here

### Dependencies

- List any dependencies that are required for this change
- Include any configuration changes needed
- Note any version updates required

## Type of Change

Please mark the relevant option with an `x`:

- [ ] 🐛 Bug fix (non-breaking change which fixes an issue)
- [ ] ✨ New feature (non-breaking change which adds functionality)
- [ ] 💥 Breaking change (fix or feature that would cause existing
functionality to not work as expected)
- [ ] 📝 Documentation update (Wiki/README/Code comments)
- [ ] ♻️ Refactor (code improvement without functional changes)
- [ ] 🎨 Style update (formatting, renaming)
- [ ] 🔧 Configuration change
- [ ] 📦 Dependency update

## Testing

- [ ] I have added unit tests that prove my fix is effective or that my
feature works
- [ ] New and existing unit tests pass locally with my changes
- [ ] I have tested this code in the following browsers/environments:
[list environments]

## Quality Checklist

- [ ] I have reviewed my own code before requesting review
- [ ] I have verified there are no other open Pull Requests for the same
update/change
- [ ] All CI/CD pipelines pass without errors or warnings
- [ ] My code follows the established style guidelines of this project
- [ ] I have added necessary documentation (if appropriate)
- [ ] I have commented my code, particularly in complex areas
- [ ] I have made corresponding changes to the README and other relevant
documentation
- [ ] My changes generate no new warnings
- [ ] I have performed a self-review of my own code
- [ ] My code is properly formatted according to project standards

## Screenshots/Recordings (if appropriate)

[Add screenshots or recordings that demonstrate the changes]

## Additional Notes

[Add any additional information that might be helpful for reviewers]

Author: ShocOne

.github/workflows/bi-weekly-tests.yml

@@ -215,25 +215,25 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        include: # testing both ubuntu-24.04-arm and ubuntu-22.04-arm-4c-l
+        include: # testing both ubuntu-24.04-arm and ubuntu-24.04-arm
           - service: applications
-            runner: ubuntu-22.04-arm-4c-l
+            runner: ubuntu-24.04-arm
           - service: device_and_app_management
-            runner: ubuntu-22.04-arm-4c-l
+            runner: ubuntu-24.04-arm
           - service: device_management
-            runner: ubuntu-22.04-arm-4c-l
+            runner: ubuntu-24.04-arm
           - service: groups
-            runner: ubuntu-22.04-arm-4c-l
+            runner: ubuntu-24.04-arm
           - service: identity_and_access
-            runner: ubuntu-22.04-arm-4c-l
+            runner: ubuntu-24.04-arm
           - service: m365_admin
-            runner: ubuntu-22.04-arm-4c-l
+            runner: ubuntu-24.04-arm
           - service: multitenant_management
-            runner: ubuntu-22.04-arm-4c-l
+            runner: ubuntu-24.04-arm
           - service: utility
-            runner: ubuntu-22.04-arm-4c-l
+            runner: ubuntu-24.04-arm
           - service: windows_365
-            runner: ubuntu-22.04-arm-4c-l
+            runner: ubuntu-24.04-arm
     steps:
       - name: Harden Runner
         uses: step-security/harden-runner@95d9a5deda9de15063e7595e9719c11c38c90ae2 # v2.13.2

scripts/pipeline/run-tests.py

@@ -1,16 +1,42 @@
 #!/usr/bin/env python3
-"""Test runner for nightly acceptance tests.
+"""Test runner for Terraform provider acceptance tests.
 
-This script runs Terraform provider tests sequentially, one package at a time,
-to conserve memory and provide better progress visibility.
+This script runs Terraform provider tests sequentially, one Go package at a time,
+to conserve memory on resource-constrained runners. Supports configurable parallelism
+and memory management options.
 
 Usage:
-    ./run-tests.py <type> [service] [coverage-file] [test-output-file]
+    ./run-tests.py <type> [service] [coverage-file] [test-output-file] [options]
+
+Positional Arguments:
+    type              Test type: provider-core, resources, or datasources
+    service           Service name (required for resources/datasources)
+    coverage-file     Coverage output file (default: coverage.txt)
+    test-output-file  Test log output file (default: test-output.log)
+
+Memory & Parallelism Options:
+    --max-procs N          GOMAXPROCS - max CPU cores for Go (default: 2)
+    --test-parallel N      Tests to run in parallel within a package (default: 1)
+    --pkg-parallel N       Packages to build/test in parallel (default: 1)
+    --race / --no-race     Enable/disable race detection (auto: on for provider-core)
+    --skip-enumeration     Skip test enumeration phase for faster startup
+    --force-gc             Force garbage collection between packages (default: enabled)
+    --no-force-gc          Disable forced garbage collection
 
-Types:
-    provider-core: Core provider tests (client, helpers, provider, utilities)
-    resources: Resource tests for a specific service
-    datasources: Datasource tests for a specific service
+Examples:
+    # Low memory mode (8GB runners) - default settings
+    ./run-tests.py resources identity_and_access coverage.txt output.log
+
+    # Ultra-conservative mode (minimize memory)
+    ./run-tests.py resources identity_and_access coverage.txt output.log \
+        --max-procs 1 --test-parallel 1 --pkg-parallel 1 --skip-enumeration --no-race
+
+    # Higher performance mode (16GB+ runners)
+    ./run-tests.py resources identity_and_access coverage.txt output.log \
+        --max-procs 4 --test-parallel 2 --pkg-parallel 1
+
+    # Show help
+    ./run-tests.py --help
 """
 
 import os
@@ -230,9 +256,9 @@ def parse_test_results(output_file: str, category: str, service: str) -> None:
 
 
 def run_provider_core_tests(coverage_file: str, test_output_file: str, 
-                           max_procs: int = 2, test_parallel: int = 1, 
-                           pkg_parallel: int = 1, use_race: bool = True,
-                           skip_enumeration: bool = False, force_gc: bool = True) -> int:
+                            max_procs: int = 2, test_parallel: int = 1, 
+                            pkg_parallel: int = 1, use_race: bool = True,
+                            skip_enumeration: bool = False, force_gc: bool = True) -> int:
     """Run provider core tests sequentially, one package at a time to conserve memory.
 
     Discovers all test packages in core directories (client, helpers, provider, utilities),