docs: Add documentation for TestContext.Parameters

docs/docs/execution/parameters.md

@@ -0,0 +1,102 @@
+# Test Parameters
+
+TUnit allows you to pass custom key-value parameters to your tests at runtime using the `--test-parameter` command-line option. These parameters are accessible via `TestContext.Parameters`.
+
+## Passing Parameters
+
+Pass parameters when running your tests using the `--test-parameter` flag with `KEY=VALUE` syntax:
+
+```bash
+dotnet run --test-parameter environment=staging
+dotnet run --test-parameter environment=staging --test-parameter api-url=https://api.example.com
+```
+
+You can pass multiple values for the same key:
+
+```bash
+dotnet run --test-parameter browser=chrome --test-parameter browser=firefox
+```
+
+## Accessing Parameters in Tests
+
+Parameters are available as a static dictionary on `TestContext`:
+
+```csharp
+public class MyTests
+{
+    [Test]
+    public async Task ConnectsToCorrectEnvironment()
+    {
+        var environments = TestContext.Parameters["environment"];
+        var environment = environments.First(); // "staging"
+
+        // Use the parameter to configure your test
+        var baseUrl = environment switch
+        {
+            "production" => "https://api.example.com",
+            "staging" => "https://staging.api.example.com",
+            _ => "http://localhost:5000"
+        };
+
+        // ...
+    }
+}
+```
+
+`TestContext.Parameters` is of type `IReadOnlyDictionary<string, List<string>>`. Each key maps to a list of values, since the same key can be specified multiple times on the command line.
+
+## Common Use Cases
+
+### Environment-specific configuration
+
+```csharp
+[Before(Test)]
+public void SetupEnvironment()
+{
+    if (TestContext.Parameters.TryGetValue("environment", out var values))
+    {
+        Environment.SetEnvironmentVariable("TEST_ENV", values.First());
+    }
+}
+```
+
+### Conditional test logic
+
+```csharp
+[Test]
+public async Task IntegrationTest()
+{
+    if (!TestContext.Parameters.ContainsKey("run-integration"))
+    {
+        Assert.Skip("Integration tests require --test-parameter run-integration=true");
+    }
+
+    // Run the integration test...
+}
+```
+
+### Passing secrets or connection strings
+
+```csharp
+[Test]
+public async Task DatabaseTest()
+{
+    if (!TestContext.Parameters.TryGetValue("connection-string", out var connectionStrings))
+    {
+        Assert.Skip("Requires --test-parameter connection-string=...");
+    }
+
+    using var connection = new SqlConnection(connectionStrings.First());
+    // ...
+}
+```
+
+```bash
+dotnet run --test-parameter "connection-string=Server=localhost;Database=TestDb;..."
+```
+
+## Notes
+
+- Parameters are available for the entire test session — they are not scoped to individual tests.
+- The parameter format must be `KEY=VALUE`. Values containing `=` characters are supported (only the first `=` is used as the delimiter).
+- Parameters are accessible from any test, hook, or data source via `TestContext.Parameters`.

docs/docs/writing-tests/test-context.md

@@ -78,6 +78,20 @@ These are useful for any test that needs unique resource names — database tabl
 If you're using `TUnit.AspNetCore`, the `WebApplicationTest` base class provides the same helpers as `protected` methods (`GetIsolatedName`, `GetIsolatedPrefix`). Both share the same underlying counter, so IDs are unique across all test types.
 :::
 
+## Test Parameters
+
+`TestContext.Parameters` provides access to custom key-value parameters passed at runtime via the `--test-parameter` command-line option:
+
+```csharp
+// Run with: dotnet run --test-parameter environment=staging
+if (TestContext.Parameters.TryGetValue("environment", out var values))
+{
+    var environment = values.First(); // "staging"
+}
+```
+
+See the [Test Parameters](../execution/parameters.md) guide for full details.
+
 ## Custom Properties
 
 Custom properties can be added to a test using the `[Property]` attribute. Properties are key-value pairs of strings that serve multiple purposes:

docs/sidebars.ts

@@ -159,6 +159,7 @@ const sidebars: SidebarsConfig = {
       collapsed: true,
       items: [
         'execution/test-filters',
+        'execution/parameters',
         'execution/timeouts',
         'execution/retrying',
         'execution/repeating',