From d14469ebb0720b10fe231249b32b4581e7341980 Mon Sep 17 00:00:00 2001 From: Jonathan Grynspan Date: Fri, 5 Sep 2025 13:16:39 -0400 Subject: [PATCH 1/3] Add a document describing our environment variable usage. Adds a document describing our environment variable usage for reference by developers working on Swift Testing. This document is not an API contract: the set of environment variables Swift Testing uses may change at any time. --- Documentation/EnvironmentVariables.md | 60 +++++++++++++++++++++++++++ 1 file changed, 60 insertions(+) create mode 100644 Documentation/EnvironmentVariables.md diff --git a/Documentation/EnvironmentVariables.md b/Documentation/EnvironmentVariables.md new file mode 100644 index 000000000..ad04a781b --- /dev/null +++ b/Documentation/EnvironmentVariables.md @@ -0,0 +1,60 @@ + + +# Environment variables in Swift Testing + +This document lists the environment variables that Swift Testing currently uses. +This list is meant for use by developers working on Swift Testing. + +Those environment variables marked with `*` are defined by components outside +Swift Testing. In general, environment variables that Swift Testing defines have +names prefixed with `SWT_`. + +> [!WARNING] +> This document is not an API contract. The set of environment variables Swift +> Testing uses may change at any time. + +## Console output + +| Variable Name | Value Type | Notes | +|-|:-:|-| +| `COLORTERM`\* | `String` | Used to determine if the current terminal supports 24-bit color. Common across UNIX-like platforms. | +| `NO_COLOR`\* | `Any?` | If set to any value, disables color output regardless of terminal capabilities. | +| `SWT_ENABLE_EXPERIMENTAL_CONSOLE_OUTPUT` | `Bool` | Used to enable or disable experimental console output. | +| `SWT_SF_SYMBOLS_ENABLED` | `Bool` | Used to explicitly enable or disable SF Symbols support on macOS. | +| `TERM`\* | `String` | Used to determine if the current terminal supports 4- or 8-bit color. Common across UNIX-like platforms. | + +## Error handling + +| Variable Name | Value Type | Notes | +|-|:-:|-| +| `SWT_FOUNDATION_ERROR_BACKTRACING_ENABLED` | `Bool` | Used to explicitly enable or disable error backtrace capturing when an instance of `NSError` or `CFError` is created on Apple platforms. | +| `SWT_SWIFT_ERROR_BACKTRACING_ENABLED` | `Bool` | Used to explicitly enable or disable error backtrace capturing when a Swift error is thrown. | + +## Exit tests + +| Variable Name | Value Type | Notes | +|-|:-:|-| +| `SWT_BACKCHANNEL` | `CInt`/`HANDLE` | A file descriptor (handle on Windows) to which the exit test's 'events are written. | +| `SWT_CAPTURED_VALUES` | `CInt`/`HANDLE` | A file descriptor (handle on Windows) containing captured values passed to the exit test. | +| `SWT_CLOSEFROM` | `CInt` | Used on OpenBSD to emulate `posix_spawn_file_actions_addclosefrom_np()`. | +| `SWT_EXIT_TEST_ID` | `String` (JSON) | Specifies which exit test to run. | +| `XCTestBundlePath`\* | `String` | Used on Apple platforms to determine if Xcode is hosting the test run. | + +## Miscellaneous + +| Variable Name | Value Type | Notes | +|-|:-:|-| +| `CFFIXED_USER_HOME`\* | `String` | Used on Apple platforms to determine the user's home directory. | +| `HOME`\* | `String` | Used to determine the user's home directory. | +| `SIMULATOR_RUNTIME_BUILD_VERSION`\* | `String` | Used when running in the iOS (etc.) Simulator to determine the simulator's version. | +| `SIMULATOR_RUNTIME_VERSION`\* | `String` | Used when running in the iOS (etc.) Simulator to determine the simulator's version. | +| `SWT_PRETTY_PRINT_JSON` | `Bool` | Used to enable pretty-printed JSON output to the event stream (for debugging purposes). | +| `SWT_USE_LEGACY_TEST_DISCOVERY` | `Bool` | Used to explicitly enable or disable legacy test discovery. | From 29d8c0d84b5ccb748563b78c6f0fa45f16a8f958 Mon Sep 17 00:00:00 2001 From: Jonathan Grynspan Date: Fri, 5 Sep 2025 14:39:28 -0400 Subject: [PATCH 2/3] Update Documentation/EnvironmentVariables.md Co-authored-by: Joseph Heck --- Documentation/EnvironmentVariables.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/EnvironmentVariables.md b/Documentation/EnvironmentVariables.md index ad04a781b..c12074ae4 100644 --- a/Documentation/EnvironmentVariables.md +++ b/Documentation/EnvironmentVariables.md @@ -42,7 +42,7 @@ names prefixed with `SWT_`. | Variable Name | Value Type | Notes | |-|:-:|-| -| `SWT_BACKCHANNEL` | `CInt`/`HANDLE` | A file descriptor (handle on Windows) to which the exit test's 'events are written. | +| `SWT_BACKCHANNEL` | `CInt`/`HANDLE` | A file descriptor (handle on Windows) to which the exit test's events are written. | | `SWT_CAPTURED_VALUES` | `CInt`/`HANDLE` | A file descriptor (handle on Windows) containing captured values passed to the exit test. | | `SWT_CLOSEFROM` | `CInt` | Used on OpenBSD to emulate `posix_spawn_file_actions_addclosefrom_np()`. | | `SWT_EXIT_TEST_ID` | `String` (JSON) | Specifies which exit test to run. | From 95daeff23576771d57bdcbd40ac0cf56c87c553b Mon Sep 17 00:00:00 2001 From: Jonathan Grynspan Date: Mon, 8 Sep 2025 11:05:07 -0400 Subject: [PATCH 3/3] Incorporate feedback. --- Documentation/EnvironmentVariables.md | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/Documentation/EnvironmentVariables.md b/Documentation/EnvironmentVariables.md index c12074ae4..a73ffdc65 100644 --- a/Documentation/EnvironmentVariables.md +++ b/Documentation/EnvironmentVariables.md @@ -26,10 +26,10 @@ names prefixed with `SWT_`. | Variable Name | Value Type | Notes | |-|:-:|-| | `COLORTERM`\* | `String` | Used to determine if the current terminal supports 24-bit color. Common across UNIX-like platforms. | -| `NO_COLOR`\* | `Any?` | If set to any value, disables color output regardless of terminal capabilities. | +| `NO_COLOR`[\*](https://no-color.org) | `Any?` | If set to any value, disables color output regardless of terminal capabilities. | | `SWT_ENABLE_EXPERIMENTAL_CONSOLE_OUTPUT` | `Bool` | Used to enable or disable experimental console output. | | `SWT_SF_SYMBOLS_ENABLED` | `Bool` | Used to explicitly enable or disable SF Symbols support on macOS. | -| `TERM`\* | `String` | Used to determine if the current terminal supports 4- or 8-bit color. Common across UNIX-like platforms. | +| `TERM`[\*](https://pubs.opengroup.org/onlinepubs/9799919799/basedefs/V1_chap08.html) | `String` | Used to determine if the current terminal supports 4- or 8-bit color. Common across UNIX-like platforms. | ## Error handling @@ -38,6 +38,13 @@ names prefixed with `SWT_`. | `SWT_FOUNDATION_ERROR_BACKTRACING_ENABLED` | `Bool` | Used to explicitly enable or disable error backtrace capturing when an instance of `NSError` or `CFError` is created on Apple platforms. | | `SWT_SWIFT_ERROR_BACKTRACING_ENABLED` | `Bool` | Used to explicitly enable or disable error backtrace capturing when a Swift error is thrown. | +## Event streams + +| Variable Name | Value Type | Notes | +|-|:-:|-| +| `SWT_EXPERIMENTAL_EVENT_STREAM_FIELDS_ENABLED` | `Bool` | Used to explicitly enable or disable experimental fields in the JSON event stream. | +| `SWT_PRETTY_PRINT_JSON` | `Bool` | Used to enable pretty-printed JSON output to the event stream (for debugging purposes). | + ## Exit tests | Variable Name | Value Type | Notes | @@ -53,8 +60,7 @@ names prefixed with `SWT_`. | Variable Name | Value Type | Notes | |-|:-:|-| | `CFFIXED_USER_HOME`\* | `String` | Used on Apple platforms to determine the user's home directory. | -| `HOME`\* | `String` | Used to determine the user's home directory. | +| `HOME`[\*](https://pubs.opengroup.org/onlinepubs/9799919799/basedefs/V1_chap08.html) | `String` | Used to determine the user's home directory. | | `SIMULATOR_RUNTIME_BUILD_VERSION`\* | `String` | Used when running in the iOS (etc.) Simulator to determine the simulator's version. | | `SIMULATOR_RUNTIME_VERSION`\* | `String` | Used when running in the iOS (etc.) Simulator to determine the simulator's version. | -| `SWT_PRETTY_PRINT_JSON` | `Bool` | Used to enable pretty-printed JSON output to the event stream (for debugging purposes). | | `SWT_USE_LEGACY_TEST_DISCOVERY` | `Bool` | Used to explicitly enable or disable legacy test discovery. |