docs: improve dotnet intro

docs/src/codegen-intro.md

@@ -29,7 +29,7 @@ playwright codegen demo.playwright.dev/todomvc
 ```
 
 ```bash csharp
-pwsh bin/Debug/netX/playwright.ps1 codegen demo.playwright.dev/todomvc
+pwsh bin/Debug/net8.0/playwright.ps1 codegen demo.playwright.dev/todomvc
 ```
 
 ### Recording a test

docs/src/intro-csharp.md

@@ -69,13 +69,13 @@ dotnet add package Microsoft.Playwright.MSTest
 dotnet build
 ```
 
-4. Install required browsers by replacing `netX` with the actual output folder name, e.g. `net8.0`:
+1. Install required browsers. This example uses `net8.0`, if you are using a different version of .NET you will need to adjust the command and change `net8.0` to your version.
 
 ```bash
-pwsh bin/Debug/netX/playwright.ps1 install
+pwsh bin/Debug/net8.0/playwright.ps1 install
 ```
 
-If `pwsh` is not available, you have to [install PowerShell](https://docs.microsoft.com/powershell/scripting/install/installing-powershell).
+If `pwsh` is not available, you will have to [install PowerShell](https://docs.microsoft.com/powershell/scripting/install/installing-powershell).
 
 ## Add Example Tests
 
@@ -102,28 +102,31 @@ namespace PlaywrightTests;
 
 [Parallelizable(ParallelScope.Self)]
 [TestFixture]
-public class Tests : PageTest
+public class ExampleTest : PageTest
 {
     [Test]
-    public async Task HomepageHasPlaywrightInTitleAndGetStartedLinkLinkingtoTheIntroPage()
+    public async Task HasTitle()
     {
         await Page.GotoAsync("https://playwright.dev");
 
         // Expect a title "to contain" a substring.
         await Expect(Page).ToHaveTitleAsync(new Regex("Playwright"));
+    }
 
-        // create a locator
+    [Test]
-        var getStarted = Page.GetByRole(AriaRole.Link, new() { Name = "Get started" });
+    public async Task GetStartedLink()
-
+    {
-        // Expect an attribute "to be strictly equal" to the value.
+        await Page.GotoAsync("https://playwright.dev");
-        await Expect(getStarted).ToHaveAttributeAsync("href", "/docs/intro");
 
         // Click the get started link.
-        await getStarted.ClickAsync();
+        await Page.GetByRole(AriaRole.Link, new() { Name = "Get started" }).ClickAsync();
 
         // Expects the URL to contain intro.
         await Expect(Page).ToHaveURLAsync(new Regex(".*intro"));
-    }
+
+        // Expects page to have a heading with the name of Installation.
+        await Expect(Page.GetByRole(AriaRole.Heading, new() { Name = "Installation" })).ToBeVisibleAsync();
+    } 
 }
 ```
 
@@ -140,28 +143,31 @@ using Microsoft.VisualStudio.TestTools.UnitTesting;
 namespace PlaywrightTests;
 
 [TestClass]
-public class UnitTest1 : PageTest
+public class ExampleTest : PageTest
 {
     [TestMethod]
-    public async Task HomepageHasPlaywrightInTitleAndGetStartedLinkLinkingtoTheIntroPage()
+    public async Task HasTitle()
     {
         await Page.GotoAsync("https://playwright.dev");
 
         // Expect a title "to contain" a substring.
         await Expect(Page).ToHaveTitleAsync(new Regex("Playwright"));
+    }
 
-        // create a locator
+    [TestMethod]
-        var getStarted = Page.GetByRole(AriaRole.Link, new() { Name = "Get started" });
+    public async Task GetStartedLink()
-
+    {
-        // Expect an attribute "to be strictly equal" to the value.
+        await Page.GotoAsync("https://playwright.dev");
-        await Expect(getStarted).ToHaveAttributeAsync("href", "/docs/intro");
 
         // Click the get started link.
-        await getStarted.ClickAsync();
+        await Page.GetByRole(AriaRole.Link, new() { Name = "Get started" }).ClickAsync();
 
         // Expects the URL to contain intro.
         await Expect(Page).ToHaveURLAsync(new Regex(".*intro"));
-    }
+
+        // Expects page to have a heading with the name of Installation.
+        await Expect(Page.GetByRole(AriaRole.Heading, new() { Name = "Installation" })).ToBeVisibleAsync();
+    } 
 }
 ```
 
@@ -183,19 +189,20 @@ By default tests will be run on Chromium. This can be configured via the `BROWSE
 <TabItem value="nunit">
 
 ```bash
-dotnet test -- NUnit.NumberOfTestWorkers=5
+dotnet test
 ```
 
 </TabItem>
 <TabItem value="mstest">
 
 ```bash
-dotnet test -- MSTest.Parallelize.Workers=5
+dotnet test
 ```
 
 </TabItem>
 </Tabs>
 
+
 See our doc on [Test Runners](./test-runners.md) to learn more about running tests in headed mode, running multiple tests, running specific configurations etc.
 
 ## System requirements
@@ -209,7 +216,7 @@ See our doc on [Test Runners](./test-runners.md) to learn more about running tes
 
 - [Write tests using web first assertions, page fixtures and locators](./writing-tests.md)
 - [Run single test, multiple tests, headed mode](./running-tests.md)
-- [Learn more about the NUnit and MSTest base classes](./test-runners.md)
 - [Generate tests with Codegen](./codegen.md)
 - [See a trace of your tests](./trace-viewer-intro.md)
-- [Using Playwright as library](./library.md)
+- [Run tests on CI](./ci-intro.md)
+- [Learn more about the NUnit and MSTest base classes](./test-runners.md)

docs/src/running-tests-csharp.md

@@ -7,57 +7,98 @@ title: "Running and debugging tests"
 
 You can run a single test, a set of tests or all tests. Tests can be run on different browsers. By default, tests are run in a headless manner, meaning no browser window will be opened while running the tests and results will be seen in the terminal. If you prefer, you can run your tests in headed mode by using the `headless` test run parameter.
 
-- Running all tests
+**You will learn**
 
-  ```bash
+- [How to run tests from the command line](/running-tests.md#command-line)
-  dotnet test
+- [How to debug tests](/running-tests.md#debugging-tests)
-  ```
+- [How to open the HTML test reporter](/running-tests.md#test-reports)
 
-- Running a single test file
 
-  ```bash
+## Running tests
-  dotnet test --filter "MyClassName"
-  ```
 
-- Run a set of test files
+### Run all tests
 
-  ```bash
+Use the following command to run all tests.
-  dotnet test --filter "MyClassName1|MyClassName2"
-  ```
 
-- Run the test with the title
+```bash
+dotnet test
+```
 
-  ```bash
+### Run tests on different browsers
-  dotnet test --filter "Name~TestMethod1"
-  ```
 
-- Running Tests on specific browsers
+To specify which browser you would like to run your tests on, use the `Playwright.BrowserName=` flag followed by the name of the browser.
 
-  ```bash
+```bash
-  dotnet test -- Playwright.BrowserName=webkit
+dotnet test -- Playwright.BrowserName=webkit
-  ```
+```
 
-- Running Tests on multiple browsers
+To specify multiple browsers to run your tests on, use the `--project` flag multiple times followed by the name of each browser.
 
-  To run your test on multiple browsers or configurations, you need to invoke the `dotnet test` command multiple times. There you can then either specify the `BROWSER` environment variable or set the `Playwright.BrowserName` via the runsettings file:
+To run your test on multiple browsers or configurations, you need to invoke the `dotnet test` command multiple times. There you can then either specify the `BROWSER` environment variable or set the `Playwright.BrowserName` via the runsettings file:
 
-  ```bash
+```bash
-  dotnet test --settings:chromium.runsettings
+dotnet test --settings:chromium.runsettings
-  dotnet test --settings:firefox.runsettings
+dotnet test --settings:firefox.runsettings
-  dotnet test --settings:webkit.runsettings
+dotnet test --settings:webkit.runsettings
-  ```
+```
 
-  ```xml
+```xml
-  <?xml version="1.0" encoding="utf-8"?>
+<?xml version="1.0" encoding="utf-8"?>
   <RunSettings>
     <Playwright>
       <BrowserName>chromium</BrowserName>
     </Playwright>
   </RunSettings>
-  ```
+```
 
 For more information see [selective unit tests](https://docs.microsoft.com/en-us/dotnet/core/testing/selective-unit-tests?pivots=mstest) in the Microsoft docs.
 
+### Run specific tests
+
+To run a single test file, use the filter flag followed by the class name of the test you want to run.
+
+```bash
+dotnet test --filter "ExampleTest"
+```
+
+To run a set of test files, use the filter flag followed by the class names of the tests you want to run.
+
+```bash
+dotnet test --filter "ExampleTest1|ExampleTest2"
+```
+
+To run a test with a specific title use the filter flag followed by *Name~* and the title of the test.
+
+```bash
+dotnet test --filter "Name~GetStartedLink"
+```
+
+### Run tests with multiple workers:
+
+<Tabs
+  groupId="test-runners"
+  defaultValue="nunit"
+  values={[
+    {label: 'NUnit', value: 'nunit'},
+    {label: 'MSTest', value: 'mstest'}
+  ]
+}>
+<TabItem value="nunit">
+
+```bash
+dotnet test -- NUnit.NumberOfTestWorkers=5
+```
+
+</TabItem>
+<TabItem value="mstest">
+
+```bash
+dotnet test -- MSTest.Parallelize.Workers=5
+```
+
+</TabItem>
+</Tabs>
+
 ## Debugging Tests
 
 Since Playwright runs in .NET, you can debug it with your debugger of choice in e.g. Visual Studio Code or Visual Studio. Playwright comes with the Playwright Inspector which allows you to step through Playwright API calls, see their debug logs and explore [locators](./locators.md).
@@ -76,7 +117,7 @@ $env:PWDEBUG=1
 dotnet test
 ```
 
-<img width="712" alt="Playwright Inspector" src="https://user-images.githubusercontent.com/883973/108614092-8c478a80-73ac-11eb-9597-67dfce110e00.png"></img>
+![debugging tests with playwright inspector](https://github.com/microsoft/playwright/assets/13063165/a1e758d3-d379-414f-be0b-7339f12bb635)
 
 Check out our [debugging guide](./debug.md) to learn more about the [Playwright Inspector](./debug.md#playwright-inspector) as well as debugging with [Browser Developer tools](./debug.md#browser-developer-tools).
 

docs/src/trace-viewer-intro-csharp-java-python.md

@@ -10,7 +10,6 @@ Playwright Trace Viewer is a GUI tool that lets you explore recorded Playwright
 **You will learn**
 
 - How to record a trace
-- How to open the HTML report
 - How to open the trace viewer
 
 ## Recording a trace
@@ -155,7 +154,7 @@ using Microsoft.Playwright.MSTest;
 namespace PlaywrightTestsMSTest;
 
 [TestClass]
-public class UnitTest1 : PageTest
+public class ExampleTest : PageTest
 {
     [TestInitialize]
     public async Task TestInitialize()
@@ -173,19 +172,19 @@ public class UnitTest1 : PageTest
     public async Task TestCleanup()
     {
         // This will produce e.g.:
-        // bin/Debug/net8.0/playwright-traces/PlaywrightTests.UnitTest1.zip
+        // bin/Debug/net8.0/playwright-traces/PlaywrightTests.ExampleTest.GetStartedLink.zip
         await Context.Tracing.StopAsync(new()
         {
             Path = Path.Combine(
                 Environment.CurrentDirectory,
                 "playwright-traces",
-                $"{TestContext.FullyQualifiedTestClassName}.zip"
+                $"{TestContext.FullyQualifiedTestClassName}.{TestContext.TestName}.zip"
             )
         });
     }
 
     [TestMethod]
-    public async Task TestYourOnlineShop()
+    public async Task GetStartedLink()
     {
         // ...
     }
@@ -199,7 +198,7 @@ This will record the trace and place it into the `bin/Debug/net8.0/playwright-tr
 
 ## Opening the trace
 
-You can open the saved trace using the Playwright CLI or in your browser on [`trace.playwright.dev`](https://trace.playwright.dev). Make sure to add the full path to where your `trace.zip` file is located. This should include the `test-results` directory followed by the test name and then `trace.zip`.
+You can open the saved trace using the Playwright CLI or in your browser on [`trace.playwright.dev`](https://trace.playwright.dev). Make sure to add the full path to where your `trace.zip` file is located.
 
 ```bash java
 mvn exec:java -e -D exec.mainClass=com.microsoft.playwright.CLI -D exec.args="show-trace trace.zip"
@@ -210,14 +209,21 @@ playwright show-trace trace.zip
 ```
 
 ```bash csharp
-pwsh bin/Debug/netX/playwright.ps1 show-trace trace.zip
+pwsh bin/Debug/net8.0/playwright.ps1 show-trace bin/Debug/net8.0/playwright-traces/PlaywrightTests.ExampleTest.GetStartedLink.zip
 ```
-## Viewing the trace
 
 View traces of your test by clicking through each action or hovering using the timeline and see the state of the page before and after the action. Inspect the log, source and network during each step of the test. The trace viewer creates a DOM snapshot so you can fully interact with it, open devtools etc.
 
+######
+* langs: python, java
+
 ![playwright trace viewer](https://github.com/microsoft/playwright/assets/13063165/10fe3585-8401-4051-b1c2-b2e92ac4c274)
 
+######
+* langs: csharp
+
+![playwright trace viewer dotnet](https://github.com/microsoft/playwright/assets/13063165/3baf2dcf-46f9-4dd7-8fcc-91c880e10a2e)
+
 To learn more check out our detailed guide on [Trace Viewer](/trace-viewer.md).
 
 ## What's next

docs/src/writing-tests-csharp.md

@@ -5,9 +5,33 @@ title: "Writing tests"
 
 ## Introduction
 
-Playwright assertions are created specifically for the dynamic web. Checks are automatically retried until the necessary conditions are met. Playwright comes with [auto-wait](./actionability.md) built in meaning it waits for elements to be actionable prior to performing actions. Playwright provides the [Expect](./test-assertions) function to write assertions.
+Playwright tests are simple, they
 
-Take a look at the example test below to see how to write a test using using [locators](/locators.md) and web first assertions.
+- **perform actions**, and
+- **assert the state** against expectations.
+
+There is no need to wait for anything prior to performing an action: Playwright
+automatically waits for the wide range of [actionability](./actionability.md)
+checks to pass prior to performing each action.
+
+There is also no need to deal with the race conditions when performing the checks -
+Playwright assertions are designed in a way that they describe the expectations
+that need to be eventually met.
+
+That's it! These design choices allow Playwright users to forget about flaky
+timeouts and racy checks in their tests altogether.
+
+**You will learn**
+
+- [How to write the first test](/writing-tests.md#first-test)
+- [How to perform actions](/writing-tests.md#actions)
+- [How to use assertions](/writing-tests.md#assertions)
+- [How tests run in isolation](/writing-tests.md#test-isolation)
+- [How to use test hooks](/writing-tests.md#using-test-hooks)
+  
+## First test
+
+Take a look at the following example to see how to write a test.
 
 <Tabs
   groupId="test-runners"
@@ -30,30 +54,31 @@ namespace PlaywrightTests;
 
 [Parallelizable(ParallelScope.Self)]
 [TestFixture]
-public class Tests : PageTest
+public class ExampleTest : PageTest
 {
     [Test]
-    public async Task HomepageHasPlaywrightInTitleAndGetStartedLinkLinkingtoTheIntroPage()
+    public async Task HasTitle()
     {
         await Page.GotoAsync("https://playwright.dev");
 
         // Expect a title "to contain" a substring.
         await Expect(Page).ToHaveTitleAsync(new Regex("Playwright"));
+    }
 
-        // create a locator
+    [Test]
-        var getStarted = Page.GetByRole(AriaRole.Link, new() { Name = "Get started" });
+    public async Task GetStartedLink()
-
+    {
-        // Expect an attribute "to be strictly equal" to the value.
+        await Page.GotoAsync("https://playwright.dev");
-        await Expect(getStarted).ToHaveAttributeAsync("href", "/docs/intro");
 
         // Click the get started link.
-        await getStarted.ClickAsync();
+        await Page.GetByRole(AriaRole.Link, new() { Name = "Get started" }).ClickAsync();
+
+        // Expects the URL to contain intro.
+        await Expect(Page).ToHaveURLAsync(new Regex(".*intro"));
 
         // Expects page to have a heading with the name of Installation.
-        await Expect(Page
+        await Expect(Page.GetByRole(AriaRole.Heading, new() { Name = "Installation" })).ToBeVisibleAsync();
-            .GetByRole(AriaRole.Heading, new() { Name = "Installation" }))
+    } 
-            .ToBeVisibleAsync();
-    }
 }
 ```
 
@@ -70,55 +95,112 @@ using Microsoft.VisualStudio.TestTools.UnitTesting;
 namespace PlaywrightTests;
 
 [TestClass]
-public class UnitTest1 : PageTest
+public class ExampleTest : PageTest
 {
     [TestMethod]
-    public async Task HomepageHasPlaywrightInTitleAndGetStartedLinkLinkingtoTheIntroPage()
+    public async Task HasTitle()
     {
         await Page.GotoAsync("https://playwright.dev");
 
         // Expect a title "to contain" a substring.
         await Expect(Page).ToHaveTitleAsync(new Regex("Playwright"));
+    }
 
-        // create a locator
+    [TestMethod]
-        var getStarted = Page.GetByRole(AriaRole.Link, new() { Name = "Get started" });
+    public async Task GetStartedLink()
-
+    {
-        // Expect an attribute "to be strictly equal" to the value.
+        await Page.GotoAsync("https://playwright.dev");
-        await Expect(getStarted).ToHaveAttributeAsync("href", "/docs/intro");
 
         // Click the get started link.
-        await getStarted.ClickAsync();
+        await Page.GetByRole(AriaRole.Link, new() { Name = "Get started" }).ClickAsync();
 
         // Expects the URL to contain intro.
         await Expect(Page).ToHaveURLAsync(new Regex(".*intro"));
-    }
+
+        // Expects page to have a heading with the name of Installation.
+        await Expect(Page.GetByRole(AriaRole.Heading, new() { Name = "Installation" })).ToBeVisibleAsync();
+    } 
 }
 ```
 
 </TabItem>
 </Tabs>
 
-### Assertions
+## Actions
 
+### Navigation
+
+Most of the tests will start by navigating the page to a URL. After that, the test
+will be able to interact with the page elements.
+
+```csharp
+await Page.GotoAsync("https://playwright.dev");
+```
+
+Playwright will wait for the page to reach the load state prior to moving forward.
+Learn more about the [`method: Page.goto`] options.
+
+### Interactions
+
+Performing actions starts with locating the elements. Playwright uses [Locators API](./locators.md) for that. Locators represent a way to find element(s) on the page at any moment, learn more about the [different types](./locators.md) of locators available. Playwright will wait for the element to be [actionable](./actionability.md) prior to performing the action, so there is no need to wait for it to become available.
+
+
+```csharp
+// Create a locator.
+var getStarted = Page.GetByRole(AriaRole.Link, new() { Name = "Get started" });
+
+// Click it.
+await getStarted.ClickAsync();
+```
+
+In most cases, it'll be written in one line:
+
+```csharp
+await Page.GetByRole(AriaRole.Link, new() { Name = "Get started" }).ClickAsync();
+```
+
+### Basic actions
+
+This is the list of the most popular Playwright actions. Note that there are many more, so make sure to check the [Locator API](./api/class-locator.md) section to
+learn more about them.
+
+| Action | Description |
+| :- | :- |
+| [`method: Locator.check`] | Check the input checkbox |
+| [`method: Locator.click`] | Click the element |
+| [`method: Locator.uncheck`] | Uncheck the input checkbox |
+| [`method: Locator.hover`] | Hover mouse over the element |
+| [`method: Locator.fill`] | Fill the form field, input text |
+| [`method: Locator.focus`] | Focus the element |
+| [`method: Locator.press`] | Press single key |
+| [`method: Locator.setInputFiles`] | Pick files to upload |
+| [`method: Locator.selectOption`] | Select option in the drop down |
+
+## Assertions
+  
 Playwright provides an async function called [Expect](./test-assertions) to assert and wait until the expected condition is met.
 
 ```csharp
 await Expect(Page).ToHaveTitleAsync(new Regex("Playwright"));
-```
+``` 
+  
+Here is the list of the most popular async assertions. Note that there are [many more](./test-assertions.md) to get familiar with:
+
+| Assertion | Description |
+| :- | :- |
+| [`method: LocatorAssertions.toBeChecked`] | Checkbox is checked |
+| [`method: LocatorAssertions.toBeEnabled`] | Control is enabled |
+| [`method: LocatorAssertions.toBeVisible`] | Element is visible |
+| [`method: LocatorAssertions.toContainText`] | Element contains text |
+| [`method: LocatorAssertions.toHaveAttribute`] | Element has attribute |
+| [`method: LocatorAssertions.toHaveCount`] | List of elements has given length |
+| [`method: LocatorAssertions.toHaveText`] | Element matches text |
+| [`method: LocatorAssertions.toHaveValue`] | Input element has value |
+| [`method: PageAssertions.toHaveTitle`] | Page has title |
+| [`method: PageAssertions.toHaveURL`] | Page has URL |
 
 
-### Locators
+## Test Isolation
-
-[Locators](./locators.md) are the central piece of Playwright's auto-waiting and retry-ability. Locators represent a way to find element(s) on the page at any moment and are used to perform actions on elements such as `.ClickAsync` `.FillAsync` etc.
-
-```csharp
-var getStarted = Page.GetByRole(AriaRole.Link, new() { Name = "Get started" });
-
-await Expect(getStarted).ToHaveAttributeAsync("href", "/docs/installation");
-await getStarted.ClickAsync();
-```
-
-### Test Isolation
 
 The Playwright NUnit and MSTest test framework base classes will isolate each test from each other by providing a separate `Page` instance. Pages are isolated between tests due to the Browser Context, which is equivalent to a brand new browser profile, where every test gets a fresh environment, even when multiple tests run in a single Browser.
 
@@ -141,7 +223,7 @@ namespace PlaywrightTests;
 
 [Parallelizable(ParallelScope.Self)]
 [TestFixture]
-public class Tests : PageTest
+public class ExampleTest : PageTest
 {
     [Test]
     public async Task BasicTest()
@@ -162,7 +244,7 @@ using Microsoft.VisualStudio.TestTools.UnitTesting;
 namespace PlaywrightTests;
 
 [TestClass]
-public class UnitTest1 : PageTest
+public class ExampleTest : PageTest
 {
     [TestMethod]
     public async Task BasicTest()
@@ -175,7 +257,7 @@ public class UnitTest1 : PageTest
 </TabItem>
 </Tabs>
 
-### Using Test Hooks
+## Using Test Hooks
 
 You can use `SetUp`/`TearDown` in NUnit or `TestInitialize`/`TestCleanup` in MSTest to prepare and clean up your test environment:
 
@@ -198,7 +280,7 @@ namespace PlaywrightTests;
 
 [Parallelizable(ParallelScope.Self)]
 [TestFixture]
-public class Tests : PageTest
+public class ExampleTest : PageTest
 {
     [Test]
     public async Task MainNavigation()
@@ -226,7 +308,7 @@ using Microsoft.VisualStudio.TestTools.UnitTesting;
 namespace PlaywrightTests;
 
 [TestClass]
-public class UnitTest1 : PageTest
+public class ExampleTest : PageTest
 {
     [TestMethod]
     public async Task MainNavigation()
@@ -251,3 +333,5 @@ public class UnitTest1 : PageTest
 - [Run single test, multiple tests, headed mode](./running-tests.md)
 - [Generate tests with Codegen](./codegen.md)
 - [See a trace of your tests](./trace-viewer-intro.md)
+- [Run tests on CI](./ci-intro.md)
+- [Learn more about the NUnit and MSTest base classes](./test-runners.md)