docs: windows test and formatter runners (#1247)

Author: supervacuus

CHANGELOG.md

@@ -6,6 +6,10 @@
 
 - Provide `before_send_transaction` callback. ([#1236](https://github.com/getsentry/sentry-native/pull/1236))
 
+**Docs**:
+
+- Document convenience Powershell runners for formatting and tests on Windows. ([#1247](https://github.com/getsentry/sentry-native/pull/1247))
+
 ## 0.8.5
 
 **Breaking changes**:
@@ -15,7 +19,7 @@
 **Features**:
 
 - Add `sentry_value_new_user(id, username, email, ip_address)` function to avoid ambiguous user-context-keys. ([#1228](https://github.com/getsentry/sentry-native/pull/1228))
- 
+
 **Fixes**:
 
 - Remove compile-time check for the `libcurl` feature `AsynchDNS`. ([#1206](https://github.com/getsentry/sentry-native/pull/1206))

CONTRIBUTING.md

@@ -32,6 +32,12 @@ be done manually.
 
     $ black tests
 
+In Powershell on Windows you can use
+
+    $ .\scripts\run_formatters.ps1
+
+to invoke both formatters.
+
 ## Running Tests
 
     $ make test
@@ -40,6 +46,21 @@ Creates a python virtualenv, and runs all the tests through `pytest`.
 
 To run our `HTTP` proxy tests, one must add `127.0.0.1  sentry.native.test` to the `hosts` file. This is required since some transports bypass the proxy otherwise (for [example on Windows](https://learn.microsoft.com/en-us/windows/win32/wininet/enabling-internet-functionality#listing-the-proxy-bypass)).
 
+**Running tests on Windows**:
+
+The `make` scripts are not written with Windows in mind, since most Windows users use Visual Studio (Code) or CLion,
+which all have elaborate build- and run-configuration capabilities that rarely require to fall back to CLI.
+
+However, if you want to run the tests from Powershell we added a convenience script
+
+    $ .\scripts\run_tests.ps1
+
+that provides the ease of the `make`-based build with a couple of parameters which you can query with
+
+    $ Get-Help .\scripts\run_tests.ps1 -detailed
+
+It depends on `.\scripts\update_test_discovery.ps1` which updates the unit-test index like the `make` target of the same
+name.
 
 **Running integration tests manually**:
 
@@ -160,12 +181,12 @@ The example currently supports the following commands:
 - `before-transaction`: Installs a `before_transaction()` callback that updates the transaction title.
 - `discarding-before-transaction`: Installs a `before_transaction()` callback that discards the transaction.
 - `traces-sampler`: Installs a traces sampler callback function when used alongside `capture-transaction`.
-- `attach-view-hierarchy`: Adds a `view-hierarchy.json` attachment file, giving it the proper `attachment_type` and `content_type`. 
+- `attach-view-hierarchy`: Adds a `view-hierarchy.json` attachment file, giving it the proper `attachment_type` and `content_type`.
  This file can be found in `./tests/fixtures/view-hierachy.json`.
 - `set-trace`: Sets the scope `propagation_context`'s trace data to the given `trace_id="aaaabbbbccccddddeeeeffff00001111"` and `parent_span_id=""f0f0f0f0f0f0f0f0"`.
- 
+
 Only on Linux using crashpad:
-- `crashpad-wait-for-upload`: Couples application shutdown to complete the upload in the `crashpad_handler`. 
+- `crashpad-wait-for-upload`: Couples application shutdown to complete the upload in the `crashpad_handler`.
 
 Only on Windows using crashpad with its WER handler module:
 

scripts/run_tests.ps1

@@ -1,10 +1,26 @@
+<#
+.SYNOPSIS
+    A helper script to execute Native SDK tests in Windows PowerShell.
+.DESCRIPTION
+    Maintains the venv, wraps pytest for execution, and invokes update_test_discovery.ps1 to collect newly added unit tests.
+#>
 param (
+    ## Lets you run only the unit tests (default: false)
     [switch]$Unit = $false,
+    ## Cleanly reinstalls packages into the venv (default: false)
     [switch]$Clean = $false,
+    ## Lets you limit the test discovery to part of a name (default: all)
     [string]$Keyword = "",
+    ## Defines the number of parallel runners via pytest-xdist. This is highly experimental since tests remove database paths. (default: 1)
     [int]$Parallelism = 1,
+    ## Disables tests that require the crashpad WER module. (default: false)
     [switch]$WithoutCrashpadWer = $false,
-    [switch]$DisableCapture = $false
+    ## Disables stdout/stderr capture through pytest (default: false)
+    [switch]$DisableCapture = $false,
+    ## Defines the maximum number of failing tests before the test session is stopped. 0 means infinite. Will not do what you expect, together with Parallelism > 1 (default: 0)
+    [int]$MaxFail = 0,
+    ## Repeatedly runs the test suite (default: false)
+    [switch]$Repeat = $false
 )
 
 $update_test_discovery = Join-Path -Path $PSScriptRoot -ChildPath "update_test_discovery.ps1"
@@ -17,7 +33,7 @@ if ($Clean -or -not (Test-Path .\.venv))
     .\.venv\Scripts\pip.exe install --upgrade --requirement .\tests\requirements.txt
 }
 
-$pytestCommand = ".\.venv\Scripts\pytest.exe .\tests\ --verbose"
+$pytestCommand = ".\.venv\Scripts\pytest.exe .\tests\ --verbose --maxfail=$MaxFail"
 
 if ($DisableCapture) {
     $pytestCommand += " --capture=no"
@@ -42,4 +58,12 @@ elseif ($Unit)
     $pytestCommand += " -k `"unit`""
 }
 
-Invoke-Expression $pytestCommand
+do {
+    try {
+        Invoke-Expression $pytestCommand
+
+        Start-Sleep -Seconds 1
+    } catch {
+        Write-Host "An error occurred: $_"
+    }
+} while($Repeat)