From 6281b95accef1f22eabeb73f6ab45e8d36797726 Mon Sep 17 00:00:00 2001 From: Pavel Feldman Date: Thu, 20 May 2021 08:20:21 -0700 Subject: [PATCH] docs(dotnet): follow up to Anze's changes (#6672) --- docs/src/api/class-browser.md | 2 +- docs/src/auth.md | 29 +++++++++++++++-- docs/src/browsers.md | 16 ++++++++++ docs/src/ci.md | 19 ++++++++--- docs/src/cli.md | 25 ++++++++++++++- docs/src/core-concepts.md | 33 +++++++++++--------- docs/src/debug.md | 12 +++++-- docs/src/emulation.md | 59 ++++++++++++++++++++++++----------- docs/src/inspector.md | 6 ++++ docs/src/screenshots.md | 10 ++++++ 10 files changed, 167 insertions(+), 44 deletions(-) diff --git a/docs/src/api/class-browser.md b/docs/src/api/class-browser.md index 84c49cc3d4..4d8aba5d23 100644 --- a/docs/src/api/class-browser.md +++ b/docs/src/api/class-browser.md @@ -65,7 +65,7 @@ with sync_playwright() as playwright: using Microsoft.Playwright; using System.Threading.Tasks; -class BrowserExamples +class Example { public static async Task Main() { diff --git a/docs/src/auth.md b/docs/src/auth.md index db031ac954..90bcee4016 100644 --- a/docs/src/auth.md +++ b/docs/src/auth.md @@ -71,6 +71,17 @@ page.click('text=Submit') # Verify app is logged in ``` +```csharp +var page = await context.NewPageAsync(); +await page.NavigateAsync("https://github.com/login"); +// Interact with login form +await page.ClickAsync("text=Login"); +await page.FillAsync("input[name='login']", USERNAME); +await page.FillAsync("input[name='password']", PASSWORD); +await page.ClickAsync("text=Submit"); +// Verify app is logged in +``` + These steps can be executed for every browser context. However, redoing login for every test can slow down test execution. To prevent that, we will reuse existing authentication state in new browser contexts. @@ -133,6 +144,17 @@ storage_state = json.loads(os.environ["STORAGE"]) context = browser.new_context(storage_state=storage_state) ``` +```csharp +// Save storage state and store as an env variable +var storage = await context.StorageStateAsync(); + +// Create a new context with the saved storage state +var context = await browser.NewContextAsync(new BrowserNewContextOptions +{ + StorageState = storage +}); +``` + Logging in via the UI and then reusing authentication state can be combined to implement **login once and run multiple scenarios**. The lifecycle looks like: @@ -310,13 +332,16 @@ with sync_playwright() as p: ```csharp using Microsoft.Playwright; -class Guides +class Example { public async void Main() { using var playwright = await Playwright.CreateAsync(); var chromium = playwright.Chromium; - var context = chromium.LaunchPersistentContextAsync(@"C:\path\to\directory\", headless: false); + var context = chromium.LaunchPersistentContextAsync(@"C:\path\to\directory\", new BrowserTypeLaunchPersistentContextOptions + { + Headless = false + }); } } ``` diff --git a/docs/src/browsers.md b/docs/src/browsers.md index b5079ed017..a10ce559ac 100644 --- a/docs/src/browsers.md +++ b/docs/src/browsers.md @@ -67,6 +67,22 @@ browser = await playwright.chromium.launch(channel="chrome") browser = playwright.chromium.launch(channel="chrome") ``` +```csharp +using Microsoft.Playwright; +using System.Threading.Tasks; + +class Example +{ + public static async Task Main() + { + using var playwright = await Playwright.CreateAsync(); + var chromium = playwright.Chromium; + // Can be "msedge", "chrome-beta", "msedge-beta", "msedge-dev", etc. + var browser = await chromium.LaunchAsync(new BrowserTypeLaunchOptions { Channel = "chrome" }); + } +} +``` + :::note Playwright bundles a recent Chromium build, but not Google Chrome or Microsoft Edge browsers - these should be installed manually before use. ::: diff --git a/docs/src/ci.md b/docs/src/ci.md index bf574a9b47..ac99cee0cf 100644 --- a/docs/src/ci.md +++ b/docs/src/ci.md @@ -101,7 +101,10 @@ Suggested configuration ``` ```csharp - await playwright.Chromium.LaunchAsync(args: new[] { "--disable-dev-shm-usage" }); + await playwright.Chromium.LaunchAsync(new BrowserTypeLaunchOptions + { + Args = new[] { "--disable-dev-shm-usage" } + }); ``` This will write shared memory files into `/tmp` instead of `/dev/shm`. See @@ -267,12 +270,15 @@ browser = playwright.chromium.launch(chromiumSandbox=False) using Microsoft.Playwright; using System.Threading.Tasks; -class Guides +class Example { public async void Main() { using var playwright = await Playwright.CreateAsync(); - await playwright.Chromium.LaunchAsync(chromiumSandbox: false); + await playwright.Chromium.LaunchAsync(new BrowserTypeLaunchOptions + { + ChromiumSandbox = false + }); } } ``` @@ -393,12 +399,15 @@ with sync_playwright() as p: using Microsoft.Playwright; using System.Threading.Tasks; -class Guides +class Example { public async void Main() { using var playwright = await Playwright.CreateAsync(); - await playwright.Chromium.LaunchAsync(headless: false); + await playwright.Chromium.LaunchAsync(new BrowserTypeLaunchOptions + { + Headless = false + }); } } ``` diff --git a/docs/src/cli.md b/docs/src/cli.md index 7976cbc011..dd8b610ff5 100644 --- a/docs/src/cli.md +++ b/docs/src/cli.md @@ -113,7 +113,6 @@ const { chromium } = require('playwright'); ``` ```java -// FIXME import com.microsoft.playwright.*; public class Example { @@ -169,6 +168,30 @@ with sync_playwright() as p: page.pause() ``` +```csharp +using Microsoft.Playwright; +using System.Threading.Tasks; + +class Example +{ + public static async Task Main() + { + using var playwright = await Playwright.CreateAsync(); + var chromium = playwright.Chromium; + // Can be "msedge", "chrome-beta", "msedge-beta", "msedge-dev", etc. + var browser = await chromium.LaunchAsync(new BrowserTypeLaunchOptions { Headless = false }); + + // Setup context however you like. + var context = await browser.NewContextAsync(); // Pass any options + await context.RouteAsync('**/*', route => route.ContinueAsync()); + + // Pause the page, and start recording manually. + var page = await context.NewPageAsync(); + await page.PauseAsync(); + } +} +``` + ## Open pages With `open`, you can use Playwright bundled browsers to browse web pages. Playwright provides cross-platform WebKit builds that can be used to reproduce Safari rendering across Windows, Linux and macOS. diff --git a/docs/src/core-concepts.md b/docs/src/core-concepts.md index 7251e2cc31..621af0842e 100644 --- a/docs/src/core-concepts.md +++ b/docs/src/core-concepts.md @@ -67,12 +67,15 @@ with sync_playwright() as p: using Microsoft.Playwright; using System.Threading.Tasks; -class BrowserExamples +class Example { public static async Task Main() { using var playwright = await Playwright.CreateAsync(); - await using var firefox = playwright.Firefox.LaunchAsync(headless: false); + await using var firefox = playwright.Firefox.LaunchAsync(new BrowserTypeLaunchOptions + { + Headless = false + }); } } ``` @@ -199,21 +202,21 @@ using System.Threading.Tasks; class PlaywrightExample { - public static async Task Main() - { - using var playwright = await Playwright.CreateAsync(); - await using var browser = await playwright.Webkit.LaunchAsync(); - var options = new BrowserContextOptions(Playwright.Devices["iPhone 11 Pro"]) - { - Geolocation = new Geolocation() { Longitude = 12.492507f, Latitude = 41.889938f }, - Permissions = new[] { "geolocation" }, - Locale = "de-DE" - }; + public static async Task Main() + { + using var playwright = await Playwright.CreateAsync(); + await using var browser = await playwright.Webkit.LaunchAsync(); + var options = new BrowserContextNewOptions(Playwright.Devices["iPhone 11 Pro"]) + { + Geolocation = new Geolocation() { Longitude = 12.492507f, Latitude = 41.889938f }, + Permissions = new[] { "geolocation" }, + Locale = "de-DE" + }; - await using var context = await browser.NewContextAsync(options); - // do work + await using var context = await browser.NewContextAsync(options); + // do work - } + } } ``` diff --git a/docs/src/debug.md b/docs/src/debug.md index 2667f0552d..69e725f06a 100644 --- a/docs/src/debug.md +++ b/docs/src/debug.md @@ -43,7 +43,12 @@ chromium.launch(headless=False, slow_mo=100) # or firefox, webkit ``` ```csharp -await using var browser = await playwright.Chromium.LaunchAsync(headless: false, slowMo: 100); // or firefox, webkit +// Chromium, Firefox, or Webkit +await using var browser = await playwright.Chromium.LaunchAsync(new BrowserTypeLaunchOptions +{ + Headless = false, + SlowMo = 100 +}); ``` ## Browser Developer Tools @@ -80,7 +85,10 @@ await chromium.launch(devtools=True) chromium.launch(devtools=True) ``` ```csharp -await using var browser = await playwright.Chromium.LaunchAsync(devtools: true); +await using var browser = await playwright.Chromium.LaunchAsync(new BrowserTypeLaunchOptions +{ + Devtools: true +}); ``` ::: diff --git a/docs/src/emulation.md b/docs/src/emulation.md index eff3f876d1..c3b81c1e76 100644 --- a/docs/src/emulation.md +++ b/docs/src/emulation.md @@ -67,13 +67,15 @@ with sync_playwright() as playwright: using Microsoft.Playwright; using System.Threading.Tasks; -class Guides +class Example { public async void Main() { using var playwright = await Playwright.CreateAsync(); - - await using var browser = await playwright.Chromium.LaunchAsync(devtools: true); + await using var browser = await playwright.Chromium.LaunchAsync(new BrowserTypeLaunchOptions + { + Headless: False + }); var pixel2 = playwright.Devices["Pixel 2"]; await using var context = await browser.NewContextAsync(pixel2); } @@ -116,7 +118,7 @@ context = browser.new_context( ``` ```csharp -var context = await browser.NewContextAsync(userAgent: "My User Agent"); +var context = await browser.NewContextAsync(new BrowserNewContextOptions { UserAgent = "My User Agent" }); ``` ### API reference @@ -191,16 +193,20 @@ context = browser.new_context( ```csharp // Create context with given viewport -await using var context = await browser.NewContextAsync( - viewportSize: new ViewportSize() { Width = 1280, Height = 1024 }); +await using var context = await browser.NewContextAsync(new BrowserNewContextOptions +{ + ViewportSize = new ViewportSize() { Width = 1280, Height = 1024 } +}); // Resize viewport for individual page await page.SetViewportSizeAsync(1600, 1200); // Emulate high-DPI -await using var context = await browser.NewContextAsync( - viewportSize: new ViewportSize() { Width = 2560, Height = 1440 }, - deviceScaleFactor: 2); +await using var context = await browser.NewContextAsync(new BrowserNewContextOptions +{ + ViewportSize = new ViewportSize() { Width = 2560, Height = 1440 }, + DeviceScaleFactor = 2 +}); ``` ### API reference @@ -243,7 +249,11 @@ context = browser.new_context( ``` ```csharp -await using var context = await browser.NewContextAsync(locale: "de-DE", timezoneId: "Europe/Berlin"); +await using var context = await browser.NewContextAsync(new BrowserNewContextOptions +{ + Locale = "de-DE", + TimezoneId = "Europe/Berlin" +}); ``` ### API reference @@ -384,10 +394,11 @@ context = browser.new_context( ``` ```csharp -await using var context = await browser.NewContextAsync( - permissions: new[] { "geolocation" }, - geolocation: new Geolocation() { Longitude = 48.858455f, Latitude = 2.294474f } - ); +await using var context = await browser.NewContextAsync(new BrowserNewContextOptions +{ + Permissions = new[] { "geolocation" }, + Geolocation = new Geolocation() { Longitude = 48.858455f, Latitude = 2.294474f } +}); ``` Change the location later: @@ -496,16 +507,28 @@ page.emulate_media(media='print') ```csharp // Create context with dark mode -await using var context = await browser.NewContextAsync(colorScheme: ColorScheme.Dark); +await using var context = await browser.NewContextAsync(new BrowserNewContextOptions +{ + ColorScheme = ColorScheme.Dark +}); // Create page with dark mode -var page = await browser.NewPageAsync(colorScheme: ColorScheme.Dark); +var page = await browser.NewPageAsync(new BrowserNewPageOptions +{ + ColorScheme = ColorScheme.Dark +}); // Change color scheme for the page -await page.EmulateMediaAsync(ColorScheme.Dark); +await page.EmulateMediaAsync(new PageEmulateMediaOptions +{ + ColorScheme = ColorScheme.Dark +}); // Change media for page -await page.EmulateMediaAsync(Media.Print); +await page.EmulateMediaAsync(new PageEmulateMediaOptions +{ + Media = Media.Print +}); ``` ### API reference diff --git a/docs/src/inspector.md b/docs/src/inspector.md index 659aa91b4e..15c8c90190 100644 --- a/docs/src/inspector.md +++ b/docs/src/inspector.md @@ -69,6 +69,12 @@ configures Playwright for debugging and opens the inspector. page.pause() ``` + ```csharp + // Pause on the following line. + await page.PauseAsync(); + ``` + + - Use `open` or `codegen` commands in the Playwright [CLI](./cli.md): ```sh js npx playwright codegen wikipedia.org diff --git a/docs/src/screenshots.md b/docs/src/screenshots.md index 4181310d6e..b6eea21278 100644 --- a/docs/src/screenshots.md +++ b/docs/src/screenshots.md @@ -69,6 +69,11 @@ screenshot_bytes = page.screenshot() image = Image.open(io.BytesIO(screenshot_bytes)) ``` +```csharp +var bytes = await page.ScreenshotAsync(); +``` + + ## Element screenshot Sometimes it is useful to take a screenshot of a single element. @@ -93,6 +98,11 @@ element_handle = page.query_selector(".header") element_handle.screenshot(path="screenshot.png") ``` +```csharp +var elementHandle = await page.QuerySelectorAsync(".header") +await elementHandle.ScreenshotAsync(new ElementHandleScreenshotOptions { Path = "screenshot.png" }); +``` + ### API reference - [`method: Page.screenshot`] - [`method: ElementHandle.screenshot`]