In xunit.v3, how do Assert.Skip, SkipUnless/SkipWhen and Explicit = true differ from a fixed [Fact(Skip = "...")], and when do you use each?
answer
- decided while the test runs
- Assert.Skip / SkipUnless / SkipWhen(condition, reason)
- SkipUnless = nameof(static bool property)
- Skip is still required as the message
- Explicit = true is reported as not run
basics
~20 sA fixed Skip always skips. xunit.v3 adds run-time skips: Assert.Skip, SkipUnless and SkipWhen inside the test, or SkipUnless/SkipWhen naming a static bool property on the attribute. Explicit = true keeps a test out of normal runs until requested.
solid answer
~50 s`[Fact(Skip = "reason")]` is unconditional. xunit.v3 adds three run-time options. Inside a test, `Assert.Skip(reason)`, `Assert.SkipUnless(condition, reason)` and `Assert.SkipWhen(condition, reason)` throw a skip exception, so the test is reported as skipped rather than failed, which suits conditions known only after setup, such as a payment sandbox that does not answer. On the attribute, `[Fact(Skip = "Needs the Linux seat-lock driver", SkipUnless = nameof(IsLinux))]` evaluates a public static `bool` property before the test runs (`SkipType` points at another class); `Skip` is still required as the message, and setting both `SkipUnless` and `SkipWhen` is an error. `SkipExceptions = new[] { typeof(PlatformNotSupportedException) }` turns chosen exception types into skips. `Explicit = true` is different: the test is not skipped but **not run** unless explicit tests are requested, for example with `-explicit only` on the native command line, which suits slow manual checks such as a load probe against staging.
code
csharp · 19 linespublic class SeatLockTests
{
public static bool IsLinux => OperatingSystem.IsLinux();
[Fact(Skip = "Seat locks use the Linux advisory-lock driver", SkipUnless = nameof(IsLinux))]
public void Two_holds_on_one_seat_conflict() { /* ... */ }
[Fact]
public async Task Sandbox_refund_round_trips()
{
var sandbox = new PaymentSandboxClient(Environment.GetEnvironmentVariable("PAY_SANDBOX_URL"));
Assert.SkipUnless(await sandbox.IsUpAsync(TestContext.Current.CancellationToken),
"Payment sandbox unavailable");
// ... refund assertions
}
[Fact(Explicit = true)]
public async Task Booth_survives_ten_thousand_holds() { /* slow load probe */ }
}go deeper
Know that xunit.v3 can skip at run time with Assert.Skip, and that Explicit tests only run when asked.
Explain SkipUnless/SkipWhen with a static bool property, why Skip is still required, and how skipped differs from not run.
Keep skips honest in CI: replace early returns with Assert.Skip*, use failSkips where nothing may be skipped, and move expensive checks to Explicit.
Define a team policy for skipped and explicit tests, including who reviews long-lived skips and which pipelines run explicit suites.
## Four ways a test can avoid running xUnit.net v2 had one switch: `[Fact(Skip = "reason")]`, which skips the test every time until someone edits the code. Real suites also need tests that skip **sometimes**, depending on the operating system, an environment variable or an external sandbox, and tests that should run **only when asked**. xunit.v3 covers those cases with separate mechanisms, and they are reported differently. | Mechanism | Decided | Reported as | Typical use | |---|---|---|---| | `Skip = "..."` alone | at discovery | skipped | known broken, waiting for a fix | | `SkipUnless` / `SkipWhen` on the attribute | before the test runs | skipped when the condition says so | OS, environment or feature flags | | `Assert.Skip*` in the body | while the test runs | skipped | conditions found during setup | | `Explicit = true` | before the test runs | not run, unless requested | slow or manual checks | ## Conditional skips on the attribute `SkipUnless` and `SkipWhen` each take the **name** of a public static `bool` property: - `SkipUnless = nameof(IsLinux)` skips when the property returns `false`; - `SkipWhen = nameof(IsCi)` skips when it returns `true`; - the property is looked up on the test class, or on `SkipType` when that is set, so conditions can live in one shared class; - `Skip` must also be set: it becomes the message. Without it the test fails with "You must set 'Skip' when you set 'SkipUnless' or 'SkipWhen'"; - setting both properties fails the test, because they are mutually exclusive; - a missing, unreadable or non-`bool` property fails the test with a message naming the property, so a typo cannot silently turn a test off. Using `nameof(...)` keeps the reference refactoring-safe. ## Skipping from inside the test `Assert.Skip(reason)` skips unconditionally from the current line, while `Assert.SkipUnless(condition, reason)` and `Assert.SkipWhen(condition, reason)` skip conditionally. All three throw an exception whose message starts with the special token `$XunitDynamicSkip$`; the runner recognises it and records a skip with the rest of the message as the reason. Because the test has already started, the constructor has run and `Dispose` still runs afterwards. Use this when the condition is only known after some work, for example after asking the ticketing provider's sandbox for a health check. Before xunit.v3, the usual workaround was an early `return`, which reported the test as **passed** and hid the fact that nothing was verified. ## Conditions on individual theory rows The same properties exist one level down. Data attributes such as `[InlineData]` and `[MemberData]` accept `Skip`, `SkipUnless`, `SkipWhen` and `SkipType`, so a theory over seat-map formats can skip only the row that needs a Linux driver while the other rows run everywhere. The rules are the same: a `Skip` message is required, and the two conditions are mutually exclusive. ## Turning exceptions into skips `SkipExceptions = new[] { typeof(PlatformNotSupportedException) }` on `[Fact]` or `[Theory]` converts those exact exception types into skips, using the exception message as the reason. It suits code paths that legitimately throw on unsupported platforms. Keep the list narrow, since every type listed there can no longer fail the test. ## Explicit tests `[Fact(Explicit = true)]` marks a test that should run only on request, such as a five-minute load probe against a staging ticket booth. By default it is **not run**, a status distinct from skipped. The native command line takes `-explicit on` (run everything), `-explicit off` (the default) or `-explicit only`; Microsoft.Testing.Platform offers the same choice as `--explicit`. Explicit tests show up in the test list, so they are discoverable without being part of every CI run. ## Keeping skips honest - A skip is a result that says nothing was verified. The `failSkips` runner option turns skipped tests into failures for builds that must not contain any. - Prefer conditional skips to commenting tests out; the reason stays visible in every report. - Prefer `Explicit` to `Skip` for tests that work but are expensive, since "skipped" suggests something is wrong. - Review long-standing fixed `Skip` strings: a reason like "flaky" that is a year old usually means a deleted or fixed test.
- Why is Assert.Skip better than an early return when the sandbox is down?An early `return` makes the test pass, so reports claim the refund flow was verified when nothing ran. `Assert.Skip` and `Assert.SkipUnless` record a skip with a reason, which keeps the gap visible and lets `failSkips` treat it as a failure where that matters.
- How do explicit tests appear when a normal run does not include them?They are reported as not run, a separate status from skipped, and they stay in the test list. Running with `-explicit only` on the native command line, or the equivalent `--explicit only` under Microsoft.Testing.Platform, runs just those tests; `-explicit on` runs them together with everything else.
- SkipUnless works without Skip, because the property name is the message.
- Assert.Skip marks the test as failed with a skip reason attached.
- Explicit = true is just another name for Skip = "...".
- An early return is the standard xunit.v3 way to skip at run time.
- SkipUnless and SkipWhen can be combined on one test to express two conditions.
Assumes xunit.v3 4.x: Assert.Skip/SkipUnless/SkipWhen, the attribute properties SkipUnless, SkipWhen, SkipType, SkipExceptions and Explicit are not available in xUnit.net v2, where only the fixed Skip string existed.