cherry-pick(#44003): docs(dotnet): document PlaywrightAssertionException and PlaywrightException

Author: dgozman

docs/src/api/class-playwrightassertionexception.md

@@ -0,0 +1,19 @@
+# class: PlaywrightAssertionException
+* since: v1.66
+* langs: csharp
+* extends: [PlaywrightException]
+
+PlaywrightAssertionException is thrown when an [assertion](../test-assertions.md) is not met, e.g. [`method: LocatorAssertions.toBeVisible`] times out
+waiting for the element. It inherits from
+[PlaywrightException], so `catch (PlaywrightException)` blocks catch it as well.
+
+```csharp
+try
+{
+    await Expect(page.GetByRole(AriaRole.Button)).ToBeVisibleAsync();
+}
+catch (PlaywrightAssertionException e)
+{
+    Console.WriteLine($"Assertion failed: {e.Message}");
+}
+```

docs/src/api/class-playwrightexception.md

@@ -1,8 +1,28 @@
 # class: PlaywrightException
 * since: v1.10
-* langs: java
+* langs: java, csharp
 * extends: [RuntimeException]
 
 PlaywrightException is thrown whenever certain operations are terminated abnormally, e.g.
-browser closes while [`method: Page.evaluate`] is running. All Playwright exceptions
-inherit from this class.
+browser closes while [`method: Page.evaluate`] is running.
+
+```java
+try {
+  page.evaluate("() => new Promise(() => {})");
+} catch (PlaywrightException e) {
+  // When the page closes during the call, the exception message says so.
+  System.out.println(e.getMessage());
+}
+```
+
+```csharp
+try
+{
+    await page.EvaluateAsync("() => new Promise(() => {})");
+}
+catch (PlaywrightException e)
+{
+    // When the page closes during the call, the exception message says so.
+    Console.WriteLine(e.Message);
+}
+```

docs/src/test-assertions-csharp-java-python.md

@@ -109,7 +109,7 @@ tests/test_foobar.py:22: AssertionError
 ```
 
 ```bash lang=csharp
-Microsoft.Playwright.PlaywrightException : should be logged in
+Microsoft.Playwright.PlaywrightAssertionException : should be logged in
 
 Locator expected to be visible
 Call log:

docs/src/test-runners-csharp.md

@@ -5,7 +5,7 @@ title: "Test Runners"
 
 ## Introduction
 
-While Playwright for .NET isn't tied to a particular test runner or testing framework, in our experience the easiest way of getting started is by using the base classes we provide for MSTest, NUnit, xUnit, or xUnit v3. These classes support running tests on multiple browser engines, adjusting launch/context options and getting a [Page]/[BrowserContext] instance per test out of the box. 
+While Playwright for .NET isn't tied to a particular test runner or testing framework, in our experience the easiest way of getting started is by using the base classes we provide for MSTest, NUnit, xUnit, or xUnit v3. These classes support running tests on multiple browser engines, adjusting launch/context options and getting a [Page]/[BrowserContext] instance per test out of the box.
 
 Playwright and Browser instances will be reused between tests for better performance. We
 recommend running each test case in a new BrowserContext, this way browser state will be
@@ -312,7 +312,7 @@ Playwright for .NET does not retry failed tests itself, use the retries of your
 
 Add the [`Retry`](https://docs.nunit.org/articles/nunit/writing-tests/attributes/retry.html) attribute to a test method. Its argument is the total number of attempts, so `[Retry(3)]` retries a failed test up to two times.
 
-By default NUnit only retries a test that failed an NUnit assertion. Playwright assertions throw `PlaywrightException` and actions that time out throw `TimeoutException`, so pass both as `RetryExceptions`. This property requires NUnit 4.5 or later.
+By default NUnit only retries a test that failed an NUnit assertion. Playwright assertions throw [PlaywrightAssertionException], other Playwright errors throw [PlaywrightException] and actions that time out throw `TimeoutException`, so pass them all as `RetryExceptions`. This property requires NUnit 4.5 or later.
 
 ```csharp
 using Microsoft.Playwright;
@@ -325,7 +325,7 @@ namespace PlaywrightTests;
 public class MyTest : PageTest
 {
     [Test]
-    [Retry(3, RetryExceptions = [typeof(PlaywrightException), typeof(TimeoutException)])]
+    [Retry(3, RetryExceptions = [typeof(PlaywrightException), typeof(PlaywrightAssertionException), typeof(TimeoutException)])]
     public async Task TestWithRetries()
     {
         await Page.GotoAsync("https://playwright.dev");
@@ -437,7 +437,7 @@ For example, to specify the number of workers you can use `NUnit.NumberOfTestWor
 ```xml
 <?xml version="1.0" encoding="utf-8"?>
 <RunSettings>
-  <!-- NUnit adapter -->  
+  <!-- NUnit adapter -->
   <NUnit>
     <NumberOfTestWorkers>24</NumberOfTestWorkers>
   </NUnit>
@@ -448,7 +448,7 @@ For example, to specify the number of workers you can use `NUnit.NumberOfTestWor
       <DEBUG>pw:api</DEBUG>
     </EnvironmentVariables>
   </RunConfiguration>
-  <!-- Playwright -->  
+  <!-- Playwright -->
   <Playwright>
     <BrowserName>chromium</BrowserName>
     <ExpectTimeout>5000</ExpectTimeout>
@@ -467,7 +467,7 @@ For example, to specify the number of workers, you can use `MSTest.Parallelize.W
 
 ```xml
 <RunSettings>
-  <!-- MSTest adapter -->  
+  <!-- MSTest adapter -->
   <MSTest>
     <Parallelize>
       <Workers>4</Workers>
@@ -481,7 +481,7 @@ For example, to specify the number of workers, you can use `MSTest.Parallelize.W
       <DEBUG>pw:api</DEBUG>
     </EnvironmentVariables>
   </RunConfiguration>
-  <!-- Playwright -->  
+  <!-- Playwright -->
   <Playwright>
     <BrowserName>chromium</BrowserName>
     <ExpectTimeout>5000</ExpectTimeout>
@@ -512,7 +512,7 @@ For example, to specify the number of workers, you can use `xUnit.MaxParallelThr
       <DEBUG>pw:api</DEBUG>
     </EnvironmentVariables>
   </RunConfiguration>
-  <!-- Playwright -->  
+  <!-- Playwright -->
   <Playwright>
     <BrowserName>chromium</BrowserName>
     <ExpectTimeout>5000</ExpectTimeout>
@@ -542,7 +542,7 @@ For example, to specify the number of workers, you can use `xUnit.MaxParallelThr
       <DEBUG>pw:api</DEBUG>
     </EnvironmentVariables>
   </RunConfiguration>
-  <!-- Playwright -->  
+  <!-- Playwright -->
   <Playwright>
     <BrowserName>chromium</BrowserName>
     <ExpectTimeout>5000</ExpectTimeout>

utils/doclint/dotnetXmlDocumentation.js

@@ -130,6 +130,8 @@ function _wrapAndEscape(node, maxColumns = 0) {
   text = text.replace(/(?<!`)\[(.*?)\]/g, (match, link) => `<see cref="${link}"/>`);
   text = text.replace(/`([^`]*)`/g, (match, code) => `<c>${code.replace(/</g, '&lt;').replace(/>/g, '&gt;')}</c>`);
   text = text.replace(/ITimeoutError/, 'TimeoutException');
+  text = text.replace(/IPlaywrightException/g, 'PlaywrightException');
+  text = text.replace(/IPlaywrightAssertionException/g, 'PlaywrightAssertionException');
   text = text.replace(/Promise/, 'Task');
 
   const words = text.split(' ');

utils/doclint/generateDotnetApi.js

@@ -77,6 +77,8 @@ const classNameMap = new Map(documentation.classesArray.map(x => [x.name, `I${to
 // map some types that we know of
 classNameMap.set('Error', 'Exception');
 classNameMap.set('TimeoutError', 'TimeoutException');
+classNameMap.set('PlaywrightException', 'PlaywrightException');
+classNameMap.set('PlaywrightAssertionException', 'PlaywrightAssertionException');
 classNameMap.set('EvaluationArgument', 'object');
 classNameMap.set('boolean', 'bool');
 classNameMap.set('any', 'object');
@@ -135,6 +137,10 @@ function renderClass(clazz) {
   const name = classNameMap.get(clazz.name);
   if (name === 'TimeoutException')
     return;
+  if (name === 'PlaywrightException')
+    return;
+  if (name === 'PlaywrightAssertionException')
+    return;
   if (name === 'IAsyncDisposable')
     return;