docs(dotnet): add test runner docs (#6919)

docs/src/cli.md

@@ -23,7 +23,7 @@ playwright
 
 ```bash csharp
 # Install the CLI once.
-dotnet add package Microsoft.Playwright.CLI
+dotnet tool install --global Microsoft.Playwright.CLI
 # Use the tools.
 playwright
 ```

docs/src/intro-csharp.md

@@ -8,30 +8,13 @@ title: "Getting Started"
 
 ## Installation
 
-Install Microsoft.Playwright package from NuGet in Visual Studio or from the CLI in your project root directory:
+Start with installing `playwright` dotnet tool globally. This only needs to be done once. Learn more about [Playwright CLI](./cli.md) tool.
 
 ```bash
-dotnet add package Microsoft.Playwright
+dotnet tool install --global Microsoft.Playwright.CLI
 ```
 
-## Usage
-
-```csharp
-using Microsoft.Playwright;
-using System.Threading.Tasks;
-
-class Program
-{
-    public static async Task Main()
-    {
-        using var playwright = await Playwright.CreateAsync();
-        await using var browser = await playwright.Chromium.LaunchAsync();
-        // Create pages, interact with UI elements, assert values
-    }
-}
-```
-
-## First script
+## First project
 
 Create a console project and add the Playwright dependency.
 
@@ -41,29 +24,45 @@ cd pw_demo
 dotnet add package Microsoft.Playwright --prerelease
 ```
 
-Create a Program.cs that will navigate to `https://playwright.dev/dotnet` and take a screenshot in Chromium.
+Ensure browsers necessary for testing are installed.
+
+```bash
+playwright install
+```
+
+Create a `Program.cs` that will navigate to `https://playwright.dev/dotnet` and take a screenshot in Chromium.
 
 ```csharp
-using Microsoft.Playwright;
+using System;
 using System.Threading.Tasks;
+using Microsoft.Playwright.NUnit;
+using NUnit.Framework;
 
-class Program
+namespace PlaywrightTests
 {
-    public static async Task Main()
+    [Parallelizable(ParallelScope.Self)]
+    public class MyTest : PageTest
     {
-        using var playwright = await Playwright.CreateAsync();
-        await using var browser = await playwright.Chromium.LaunchAsync();
-        var page = await browser.NewPageAsync();
-        await page.GotoAsync("https://playwright.dev/dotnet");
-        await page.ScreenshotAsync(new PageScreenshotOptions { Path = "screenshot.png" });
+        [Test]
+        public async Task ShouldAdd()
+        {
+            int result = await Page.EvaluateAsync<int>("() => 7 + 3");
+            Assert.AreEqual(10, result);
+        }
+
+        [Test]
+        public async Task ShouldMultiply()
+        {
+            int result = await Page.EvaluateAsync<int>("() => 7 * 3");
+            Assert.AreEqual(21, result);
+        }
     }
 }
 ```
 
-Now build it and run it.
+Now run it.
 
 ```bash
-dotnet build
 dotnet run
 ```
 
@@ -73,12 +72,56 @@ By default, Playwright runs the browsers in headless mode. To see the browser UI
 await playwright.Firefox.LaunchAsync(new BrowserTypeLaunchOptions { Headless = false, SlowMo = 50 });
 ```
 
+## First test
+
+You can choose to use NUnit test fixtures that come bundled with Playwright. These fixtures support running tests on multiple browser engines in parallel, out of the box. Learn more about [Playwright with NUnit](./test-runners.md).
+
+```bash
+dotnet new console -n pw_test
+cd pw_test
+dotnet add package Microsoft.Playwright --prerelease
+dotnet add package Microsoft.Playwright.NUnit --prerelease
+```
+
+Ensure browsers necessary for testing are installed.
+
+```bash
+playwright install
+```
+
+Create a PageTests.cs file.
+```csharp
+using System;
+using System.Threading.Tasks;
+using Microsoft.Playwright.NUnit;
+using NUnit.Framework;
+
+namespace ExampleTest
+{
+    [Parallelizable(ParallelScope.Self)]
+    public class PageTests : PageTest
+    {
+        [Test]
+        public async Task ShouldMultiply()
+        {
+            int result = await Page.EvaluateAsync<int>("() => 7 * 3");
+            Assert.AreEqual(21, result);
+        }
+    }
+}
+```
+
+```bash
+dotnet build
+dotnet test -- NUnit.NumberOfTestWorkers=5
+```
+
 ## Record scripts
 
-Command Line Interface [CLI](./cli.md) can be used to record user interactions and generate C# code.
+[Command Line Interface](./cli.md) can be used to record user interactions and generate C# code.
 
 ```bash
-# FIXME:
+playwright codegen
 ```
 
 ## System requirements

docs/src/test-runners-csharp.md

@@ -0,0 +1,112 @@
+---
+id: test-runners
+title: "Test Runners"
+---
+
+With a few lines of code, you can hook up Playwright to your favorite .NET test runner.
+
+Playwright and Browser instances can be reused between tests for better performance. We
+recommend running each test case in a new BrowserContext, this way browser state will be
+isolated between the tests.
+
+<!-- TOC -->
+
+## Creating NUnit project
+
+```bash
+dotnet new console -n pw_test
+cd pw_test
+dotnet add package Microsoft.Playwright --prerelease
+dotnet add package Microsoft.Playwright.NUnit --prerelease
+```
+
+Ensure browsers necessary for testing are installed.
+
+```bash
+playwright install
+```
+
+Create a PageTests.cs file.
+
+```csharp
+using System;
+using System.Threading.Tasks;
+using Microsoft.Playwright.NUnit;
+using NUnit.Framework;
+
+namespace PlaywrightTests
+{
+    [Parallelizable(ParallelScope.Self)]
+    public class MyTest : PageTest
+    {
+        [Test]
+        public async Task ShouldAdd()
+        {
+            int result = await Page.EvaluateAsync<int>("() => 7 + 3");
+            Assert.AreEqual(10, result);
+        }
+
+        [Test]
+        public async Task ShouldMultiply()
+        {
+            int result = await Page.EvaluateAsync<int>("() => 7 * 3");
+            Assert.AreEqual(21, result);
+        }
+    }
+}
+```
+
+Run your tests against Chromium
+
+```bash
+dotnet build
+dotnet test
+```
+
+Run your tests against WebKit
+
+Windows
+
+```bash
+set BROWSER=webkit
+dotnet test
+```
+
+Linux & Mac
+
+```bash
+BROWSER=webkit dotnet test
+```
+
+Run your tests with GUI
+
+Window
+
+```bash
+set HEADED=1
+dotnet test
+```
+
+Linux & Mac
+
+```bash
+HEADED=1 dotnet test
+```
+
+## Running NUnit tests in Parallel
+
+By default NUnit will run all test files in parallel, while running tests inside each file sequentially. It will create as many processes as there are cores on the host system. You can adjust this behavior using the NUnit.NumberOfTestWorkers parameter.
+
+For CPU-bound tests, we recommend using as many workers as there are cores on your system, divided by 2. For IO-bound tests you can use as many workers as you have cores.
+
+## Base NUnit classes for Playwright
+
+There are few base classes available to you in Microsoft.Playwright.NUnit namespace:
+
+|Test          |Description|
+|--------------|-----------|
+|PageTest      |Each test gets a fresh copy of a web [Page] created in its own unique [BrowserContext]. Extending this class is the simplest way of writing a fully-functional Playwright test.<br></br><br></br>Note: You can override the `ContextOptions` method in each test file to control context options, the ones typically passed into the [`method: Browser.newContext`] method. That way you can specify all kinds of emulation options for your test file individually.|
+|ContextTest   |Each test will get a fresh copy of a [BrowserContext]. You can create as many pages in this context as you'd like. Using this test is the easiest way to test multi-page scenarios where you need more than one tab.<br></br><br></br>Note: You can override the `ContextOptions` method in each test file to control context options, the ones typically passed into the [`method: Browser.newContext`] method. That way you can specify all kinds of emulation options for your test file individually.|
+|BrowserTest   |Each test will get a browser and can create as many contexts as it likes. Each test is responsible for cleaning up all the contexts it created.|
+|PlaywrightTest|This gives each test a Playwright object so that the test could start and stop as many browsers as it likes.|
+