From 140a871daff6a8eff2702cfc5473eeed68e03c31 Mon Sep 17 00:00:00 2001
From: Dmitry Gozman <dgozman@gmail.com>
Date: Thu, 12 Nov 2026 15:24:50 +0000
Subject: [PATCH] docs(dotnet): add Expect(callback).ToPassAsync()

References: https://github.com/microsoft/playwright-dotnet/issues/2314
---
 docs/src/api/class-functionassertions.md      | 58 +++++++++++++++++++
 docs/src/api/class-playwrightassertions.md    | 24 ++++++++
 .../src/test-assertions-csharp-java-python.md | 35 +++++++++++
 3 files changed, 117 insertions(+)
 create mode 100644 docs/src/api/class-functionassertions.md

diff --git a/docs/src/api/class-functionassertions.md b/docs/src/api/class-functionassertions.md
new file mode 100644
index 0000000000000..1d913732ff5fa
--- /dev/null
+++ b/docs/src/api/class-functionassertions.md
@@ -0,0 +1,58 @@
+# class: FunctionAssertions
+* since: v1.66
+* langs: csharp
+
+The [FunctionAssertions] class provides assertion methods that retry a block of code. A new instance of [FunctionAssertions] is created by calling [`method: PlaywrightAssertions.expectFunction`]:
+
+```csharp
+using Microsoft.Playwright;
+using Microsoft.Playwright.MSTest;
+
+namespace PlaywrightTests;
+
+[TestClass]
+public class ExampleTests : PageTest
+{
+    [TestMethod]
+    public async Task ApiEventuallySucceeds()
+    {
+        await Expect(async () =>
+        {
+            var response = await Page.APIRequest.GetAsync("https://api.example.com");
+            Assert.AreEqual(200, response.Status);
+        }).ToPassAsync();
+    }
+}
+```
+
+## async method: FunctionAssertions.toPass
+* since: v1.66
+
+Retries the callback until it completes without throwing an exception, or until the timeout is reached. When the timeout is reached, throws a [PlaywrightAssertionException] with the last exception that the callback has thrown.
+
+**Usage**
+
+```csharp
+await Expect(async () =>
+{
+    var response = await Page.APIRequest.GetAsync("https://api.example.com");
+    Assert.AreEqual(200, response.Status);
+}).ToPassAsync(new()
+{
+    // Probe, wait 1s, probe, wait 2s, probe, wait 10s, probe, wait 10s, probe
+    Intervals = [1_000, 2_000, 10_000],
+    Timeout = 60_000,
+});
+```
+
+### option: FunctionAssertions.toPass.intervals
+* since: v1.66
+- `intervals` <[Array]<[int]>>
+
+Time to wait between the retries in milliseconds. The last interval is used for all the following retries. Defaults to `[100, 250, 500, 1000]`.
+
+### option: FunctionAssertions.toPass.timeout
+* since: v1.66
+- `timeout` <[float]>
+
+Time to retry the callback for in milliseconds. Defaults to `30000`, change the default with `SetDefaultExpectToPassTimeout`. Pass `0` to disable the timeout.
diff --git a/docs/src/api/class-playwrightassertions.md b/docs/src/api/class-playwrightassertions.md
index aa4e0a42a4bf4..bd32064aa054f 100644
--- a/docs/src/api/class-playwrightassertions.md
+++ b/docs/src/api/class-playwrightassertions.md
@@ -95,6 +95,30 @@ PlaywrightAssertions.assertThat(response).isOK();
 
 [APIResponse] object to use for assertions.
 
+## method: PlaywrightAssertions.expectFunction
+* since: v1.66
+* langs: csharp
+  - alias-csharp: Expect
+- returns: <[FunctionAssertions]>
+
+Creates a [FunctionAssertions] object for the given callback.
+
+**Usage**
+
+```csharp
+await Expect(async () =>
+{
+    var response = await Page.APIRequest.GetAsync("https://api.example.com");
+    Assert.AreEqual(200, response.Status);
+}).ToPassAsync();
+```
+
+### param: PlaywrightAssertions.expectFunction.callback
+* since: v1.66
+- `callback` <[Func<Task>]>
+
+Callback to retry. A synchronous `Action` is accepted as well.
+
 ## method: PlaywrightAssertions.expectGeneric
 * since: v1.9
 * langs: js
diff --git a/docs/src/test-assertions-csharp-java-python.md b/docs/src/test-assertions-csharp-java-python.md
index c6ec293d482eb..aa9827faaea87 100644
--- a/docs/src/test-assertions-csharp-java-python.md
+++ b/docs/src/test-assertions-csharp-java-python.md
@@ -58,6 +58,41 @@ The following assertions will retry until the assertion passes or the assertion
 | [`method: PageAssertions.toHaveURL`] | Page has a URL |
 | [`method: APIResponseAssertions.toBeOK`] | Response has an OK status |
 
+## Expect.ToPassAsync
+* langs: csharp
+
+Prefer auto-retrying assertions whenever possible. For more complex checks, retry a block of code until it passes with [`method: FunctionAssertions.toPass`].
+
+```csharp
+await Expect(async () =>
+{
+    var response = await Page.APIRequest.GetAsync("https://api.example.com");
+    Assert.AreEqual(200, response.Status);
+}).ToPassAsync();
+```
+
+You can also specify custom timeout and retry intervals:
+
+```csharp
+await Expect(async () =>
+{
+    var response = await Page.APIRequest.GetAsync("https://api.example.com");
+    Assert.AreEqual(200, response.Status);
+}).ToPassAsync(new()
+{
+    // Probe, wait 1s, probe, wait 2s, probe, wait 10s, probe, wait 10s, probe
+    // ... Defaults to [100, 250, 500, 1000].
+    Intervals = [1_000, 2_000, 10_000],
+    Timeout = 60_000,
+});
+```
+
+By default, `ToPassAsync` retries for 30 seconds. `SetDefaultExpectTimeout` does not change this timeout, use `SetDefaultExpectToPassTimeout` instead:
+
+```csharp
+SetDefaultExpectToPassTimeout(60_000);
+```
+
 ## Soft assertions
 * langs: python