Merge branch 'master' into protocol-using-webdriver-driver

hardkoded · Sep 6, 2024 · 8b297d6 · 8b297d6
2 parents d451054 + 270c7a2
commit 8b297d6
Show file tree

Hide file tree

Showing 55 changed files with 254 additions and 156 deletions.
diff --git a/.github/workflows/on-push-do-docs.yml b/.github/workflows/on-push-do-docs.yml
@@ -3,9 +3,13 @@ on:
   push:
 jobs:
   docs:
-    runs-on: windows-latest
+    runs-on: ubuntu-latest
     steps:
     - uses: actions/checkout@v2
+    - name: Setup .NET
+      uses: actions/setup-dotnet@v3
+      with:
+        dotnet-version: 7.0.x
     - name: Run MarkdownSnippets
       run: |
         dotnet tool install --global MarkdownSnippets.Tool

diff --git a/.gitignore b/.gitignore
@@ -294,9 +294,8 @@ Thumbs.db
 
 demos/PuppeteerSharpPdfDemo/google.pdf
 demos/PuppeteerSharpPdfDemo/.local-chromium/
-docs/
+/docs
 samples/PupppeterSharpAspNetFrameworkSample/PupppeterSharpAspNetFrameworkSample/App_Data/
-
 # Visual Studio Code user config directory
 .vscode/
 tools/github-ops/.env
diff --git a/README.md b/README.md
@@ -49,8 +49,8 @@ See [this document](https://github.com/hardkoded/puppeteer-sharp/blob/master/CON
 
 ## Take screenshots
 
-<!-- snippet: ScreenshotAsync -->
-<a id='snippet-ScreenshotAsync'></a>
+<!-- snippet: screenshotasync_example -->
+<a id='snippet-screenshotasync_example'></a>
 ```cs
 var browserFetcher = new BrowserFetcher();
 await browserFetcher.DownloadAsync();
@@ -60,27 +60,27 @@ await using var page = await browser.NewPageAsync();
 await page.GoToAsync("http://www.google.com");
 await page.ScreenshotAsync(outputFile);
 ```
-<sup><a href='https://github.com/hardkoded/puppeteer-sharp/blob/master/lib/PuppeteerSharp.Tests/ScreenshotTests/PageScreenshotTests.cs#L54-L62' title='Snippet source file'>snippet source</a> | <a href='#snippet-ScreenshotAsync' title='Start of snippet'>anchor</a></sup>
+<sup><a href='https://github.com/hardkoded/puppeteer-sharp/blob/master/lib/PuppeteerSharp.Tests/ScreenshotTests/PageScreenshotTests.cs#L54-L62' title='Snippet source file'>snippet source</a> | <a href='#snippet-screenshotasync_example' title='Start of snippet'>anchor</a></sup>
 <!-- endSnippet -->
 
 You can also change the view port before generating the screenshot
 
-<!-- snippet: SetViewportAsync -->
-<a id='snippet-SetViewportAsync'></a>
+<!-- snippet: setviewportasync_example -->
+<a id='snippet-setviewportasync_example'></a>
 ```cs
 await Page.SetViewportAsync(new ViewPortOptions
 {
     Width = 500,
     Height = 500
 });
 ```
-<sup><a href='https://github.com/hardkoded/puppeteer-sharp/blob/master/lib/PuppeteerSharp.Tests/ScreenshotTests/ElementHandleScreenshotTests.cs#L13-L19' title='Snippet source file'>snippet source</a> | <a href='#snippet-SetViewportAsync' title='Start of snippet'>anchor</a></sup>
+<sup><a href='https://github.com/hardkoded/puppeteer-sharp/blob/master/lib/PuppeteerSharp.Tests/ScreenshotTests/ElementHandleScreenshotTests.cs#L13-L19' title='Snippet source file'>snippet source</a> | <a href='#snippet-setviewportasync_example' title='Start of snippet'>anchor</a></sup>
 <!-- endSnippet -->
 
 ### Generate PDF files
 
-<!-- snippet: PdfAsync -->
-<a id='snippet-PdfAsync'></a>
+<!-- snippet: pdfasync_example -->
+<a id='snippet-pdfasync_example'></a>
 ```cs
 var browserFetcher = new BrowserFetcher();
 await browserFetcher.DownloadAsync();
@@ -90,32 +90,32 @@ await page.GoToAsync("http://www.google.com"); // In case of fonts being loaded
 await page.EvaluateExpressionHandleAsync("document.fonts.ready"); // Wait for fonts to be loaded. Omitting this might result in no text rendered in pdf.
 await page.PdfAsync(outputFile);
 ```
-<sup><a href='https://github.com/hardkoded/puppeteer-sharp/blob/master/lib/PuppeteerSharp.Tests/PageTests/PdfTests.cs#L23-L33' title='Snippet source file'>snippet source</a> | <a href='#snippet-PdfAsync' title='Start of snippet'>anchor</a></sup>
+<sup><a href='https://github.com/hardkoded/puppeteer-sharp/blob/master/lib/PuppeteerSharp.Tests/PageTests/PdfTests.cs#L23-L33' title='Snippet source file'>snippet source</a> | <a href='#snippet-pdfasync_example' title='Start of snippet'>anchor</a></sup>
 <!-- endSnippet -->
 
 ### Inject HTML
 
-<!-- snippet: SetContentAsync -->
-<a id='snippet-SetContentAsync'></a>
+<!-- snippet: setcontentasync_example -->
+<a id='snippet-setcontentasync_example'></a>
 ```cs
 await using var page = await browser.NewPageAsync();
 await page.SetContentAsync("<div>My Receipt</div>");
 var result = await page.GetContentAsync();
 ```
-<sup><a href='https://github.com/hardkoded/puppeteer-sharp/blob/master/lib/PuppeteerSharp.Tests/PageTests/SetContentTests.cs#L14-L20' title='Snippet source file'>snippet source</a> | <a href='#snippet-SetContentAsync' title='Start of snippet'>anchor</a></sup>
+<sup><a href='https://github.com/hardkoded/puppeteer-sharp/blob/master/lib/PuppeteerSharp.Tests/PageTests/SetContentTests.cs#L14-L20' title='Snippet source file'>snippet source</a> | <a href='#snippet-setcontentasync_example' title='Start of snippet'>anchor</a></sup>
 <!-- endSnippet -->
 
 ### Evaluate Javascript
 
-<!-- snippet: Evaluate -->
-<a id='snippet-Evaluate'></a>
+<!-- snippet: evaluate_example -->
+<a id='snippet-evaluate_example'></a>
 ```cs
 await using var page = await browser.NewPageAsync();
 var seven = await page.EvaluateExpressionAsync<int>("4 + 3");
 var someObject = await page.EvaluateFunctionAsync<JsonElement>("(value) => ({a: value})", 5);
 Console.WriteLine(someObject.GetProperty("a").GetString());
 ```
-<sup><a href='https://github.com/hardkoded/puppeteer-sharp/blob/master/lib/PuppeteerSharp.Tests/QuerySelectorTests/ElementHandleQuerySelectorEvalTests.cs#L17-L22' title='Snippet source file'>snippet source</a> | <a href='#snippet-Evaluate' title='Start of snippet'>anchor</a></sup>
+<sup><a href='https://github.com/hardkoded/puppeteer-sharp/blob/master/lib/PuppeteerSharp.Tests/QuerySelectorTests/ElementHandleQuerySelectorEvalTests.cs#L17-L22' title='Snippet source file'>snippet source</a> | <a href='#snippet-evaluate_example' title='Start of snippet'>anchor</a></sup>
 <!-- endSnippet -->
 
 ### Wait For Selector
@@ -172,6 +172,6 @@ A massive thanks to [AWS](https://github.com/aws), who sponsored Puppeteer-sharp
 
 And a huge thanks to everyone who sponsors this project through [Github sponsors](https://github.com/sponsors/hardkoded):
 
-<!-- sponsors --><a href="https://github.com/tolgabalci"><img src="https://github.com/tolgabalci.png" width="60px" alt="Tolga Balci" /></a><a href="https://github.com/nogginbox"><img src="https://github.com/nogginbox.png" width="60px" alt="Richard Garside" /></a><a href="https://github.com/aws"><img src="https://github.com/aws.png" width="60px" alt="Amazon Web Services" /></a><!-- sponsors -->
+<!-- sponsors --><a href="https://github.com/tolgabalci"><img src="https:&#x2F;&#x2F;avatars.githubusercontent.com&#x2F;u&#x2F;2467618?u&#x3D;8ed50176b40b4e869c95c4c53137ab6a8a5fe1b1&amp;v&#x3D;4" width="60px" alt="Tolga Balci" /></a><a href="https://github.com/nogginbox"><img src="https:&#x2F;&#x2F;avatars.githubusercontent.com&#x2F;u&#x2F;729381?v&#x3D;4" width="60px" alt="Richard Garside" /></a><a href="https://github.com/aws"><img src="https:&#x2F;&#x2F;avatars.githubusercontent.com&#x2F;u&#x2F;2232217?v&#x3D;4" width="60px" alt="Amazon Web Services" /></a><!-- sponsors -->
 
 
diff --git a/docfx_project/docfx.json b/docfx_project/docfx.json
@@ -27,8 +27,8 @@
       },
       {
         "files": [
-          "examples/**.yml",
-          "examples/**.md"
+          "docs/**.yml",
+          "docs/**.md"
         ]
       },
       {

diff --git a/docfx_project/examples/AOT.md → docfx_project/docs/AOT.md b/docfx_project/examples/AOT.md → docfx_project/docs/AOT.md
diff --git a/docfx_project/examples/ChromeExtension.md → docfx_project/docs/ChromeExtension.md b/docfx_project/examples/ChromeExtension.md → docfx_project/docs/ChromeExtension.md
diff --git a/...ject/examples/DownloadFetcher.Download.md → ..._project/docs/DownloadFetcher.Download.md b/...ject/examples/DownloadFetcher.Download.md → ..._project/docs/DownloadFetcher.Download.md
@@ -13,8 +13,8 @@ You will find the available versions [here](https://googlechromelabs.github.io/c
 Once you have the version you want, you can download it using the `BrowserFetcher` class.
 
 ```cs
-<!-- snippet: CustomVersionsExample -->
-<a id='snippet-CustomVersionsExample'></a>
+<!-- snippet: customversions_example -->
+<a id='snippet-customversions_example'></a>
 ```cs
 Console.WriteLine("Downloading browsers");
 
@@ -51,6 +51,6 @@ await using (var browser = await Puppeteer.LaunchAsync(new()
     Console.WriteLine("Export completed");
 }
 ```
-<sup><a href='https://github.com/hardkoded/puppeteer-sharp/blob/master/lib/PuppeteerSharp.Tests/Browsers/Chrome/ChromeDataTests.cs#L24-L59' title='Snippet source file'>snippet source</a> | <a href='#snippet-CustomVersionsExample' title='Start of snippet'>anchor</a></sup>
+<sup><a href='https://github.com/hardkoded/puppeteer-sharp/blob/master/lib/PuppeteerSharp.Tests/Browsers/Chrome/ChromeDataTests.cs#L24-L59' title='Snippet source file'>snippet source</a> | <a href='#snippet-customversions_example' title='Start of snippet'>anchor</a></sup>
 <!-- endSnippet -->
 ```
diff --git a/docfx_project/docs/IssuesGeneratingPdfFiles.md b/docfx_project/docs/IssuesGeneratingPdfFiles.md
@@ -0,0 +1,39 @@
+# Issues generating PDF files
+_Contributors: [Dario Kondratiuk](https://github.com/kblok)_
+
+## Symptoms
+
+When generating PDF files using `PdfAsync`, everything works fine in your development environment. However, once you deploy your application to a server, you get a timeout.
+
+## Problem
+
+Since Chromium version 125, generating PDF files requires sandbox permissions. [See chromium issue](https://issues.chromium.org/issues/338553158).
+PuppeteerSharp tries to apply these permissions after the browser is downloaded, but it will proceed if this step fails. We want to ensure your application does not break if it never reaches the point of generating a PDF file.
+
+## Solution
+
+Verify whether PuppeteerSharp successfully applied the sandbox permissions. This can be done by checking the `InstalledBrowser.PermissionsFixed` property.
+
+```csharp
+var browserFetcher = new BrowserFetcher();
+var installedBrowser = await browserFetcher.DownloadAsync(BrowserFetcher.);
+
+if (!installedBrowser.PermissionsFixed)
+{
+    Console.WriteLine("Sandbox permissions were not applied. You need to run your application as an administrator.");
+    return;
+}
+```
+
+If PuppeteerSharp did not manage to apply the sandbox permissions, you can manually fix this by running the `setup.exe` file that was downloaded with the browser:
+
+```bash
+cd <path-to-browser>
+.\setup.exe --configure-browser-in-directory="<path-to-browser>"
+```
+
+If that doesn't work. You can try by fixing the permissions manually. You can find the instructions [here](https://pptr.dev/troubleshooting#chrome-reports-sandbox-errors-on-windows).
+
+## Recommended approach
+
+Installing the browser during runtime is not recommended, as it takes time and can delay your application. It is advisable to install the browser beforehand and pass the path to the `LaunchAsync` method.
diff --git a/...x_project/examples/LogCDPCommunication.md → docfx_project/docs/LogCDPCommunication.md b/...x_project/examples/LogCDPCommunication.md → docfx_project/docs/LogCDPCommunication.md
diff --git a/...ge.EvaluateExpressionAsync.GetAllLinks.md → ...ge.EvaluateExpressionAsync.GetAllLinks.md b/...ge.EvaluateExpressionAsync.GetAllLinks.md → ...ge.EvaluateExpressionAsync.GetAllLinks.md
diff --git a/...EvaluateFunctionAsync.ComplexJSObjects.md → ...EvaluateFunctionAsync.ComplexJSObjects.md b/...EvaluateFunctionAsync.ComplexJSObjects.md → ...EvaluateFunctionAsync.ComplexJSObjects.md
diff --git a/docfx_project/examples/Page.Request.md → docfx_project/docs/Page.Request.md b/docfx_project/examples/Page.Request.md → docfx_project/docs/Page.Request.md
diff --git a/..._project/examples/Page.ScreenshotAsync.md → docfx_project/docs/Page.ScreenshotAsync.md b/..._project/examples/Page.ScreenshotAsync.md → docfx_project/docs/Page.ScreenshotAsync.md
diff --git a/...ect/examples/Page.WaitForFunctionAsync.md → ...project/docs/Page.WaitForFunctionAsync.md b/...ect/examples/Page.WaitForFunctionAsync.md → ...project/docs/Page.WaitForFunctionAsync.md
diff --git a/...es/Page.WaitForSelectorAsync.Searching.md → ...cs/Page.WaitForSelectorAsync.Searching.md b/...es/Page.WaitForSelectorAsync.Searching.md → ...cs/Page.WaitForSelectorAsync.Searching.md
diff --git a/docfx_project/examples/ReuseChrome.md → docfx_project/docs/ReuseChrome.md b/docfx_project/examples/ReuseChrome.md → docfx_project/docs/ReuseChrome.md
@@ -11,15 +11,15 @@ from a location where it was previously downloaded instead of from the default l
 
 Use `BrowserFetcherOptions` to specify the full path for where to download Chrome.
 
-<!-- snippet: ReuseChromeExample -->
-<a id='snippet-ReuseChromeExample'></a>
+<!-- snippet: reusechrome_example -->
+<a id='snippet-reusechrome_example'></a>
 ```cs
 var downloadPath = "/Users/dario/chrome";
 var browserFetcherOptions = new BrowserFetcherOptions { Path = downloadPath };
 var browserFetcher = new BrowserFetcher(browserFetcherOptions);
 var installedBrowser = await browserFetcher.DownloadAsync();
 ```
-<sup><a href='https://github.com/hardkoded/puppeteer-sharp/blob/master/lib/PuppeteerSharp.Tests/Browsers/Chrome/ChromeDataTests.cs#L14-L19' title='Snippet source file'>snippet source</a> | <a href='#snippet-ReuseChromeExample' title='Start of snippet'>anchor</a></sup>
+<sup><a href='https://github.com/hardkoded/puppeteer-sharp/blob/master/lib/PuppeteerSharp.Tests/Browsers/Chrome/ChromeDataTests.cs#L14-L19' title='Snippet source file'>snippet source</a> | <a href='#snippet-reusechrome_example' title='Start of snippet'>anchor</a></sup>
 <!-- endSnippet -->
 
 Use `Puppeteer.LaunchAsync()` with `LaunchOptions` with the `LaunchOptions.ExecutablePath` property set to the

diff --git a/docfx_project/examples/index.md → docfx_project/docs/index.md b/docfx_project/examples/index.md → docfx_project/docs/index.md
diff --git a/docfx_project/examples/toc.yml → docfx_project/docs/toc.yml b/docfx_project/examples/toc.yml → docfx_project/docs/toc.yml
@@ -24,3 +24,7 @@
   items:
     - name: How to log CDP communication
       href: LogCDPCommunication.md
+- name: Troubleshooting
+  items:
+    - name: Issues generating PDF files
+      href: IssuesGeneratingPdfFiles.md
diff --git a/docfx_project/index.md b/docfx_project/index.md
@@ -10,21 +10,9 @@ This will give you priority support and code reviews (depending on the tier), an
 
 # Prerequisites
 
- * As Puppeteer-Sharp is a NetStandard 2.0 library, The minimum platform versions are .NET Framework 4.6.1 and .NET Core 2.0. [Read more](https://docs.microsoft.com/en-us/dotnet/standard/net-standard).
- * The minimum Windows versions supporting the WebSocket library are Windows 8 and Windows Server 2012. [Read more](https://docs.microsoft.com/en-us/dotnet/api/system.net.websockets?redirectedfrom=MSDN&view=netframework-4.7.2).
- * Mono is required on **Linux** if your project targets the .NET Framework 4 or earlier. Read more about installing Mono [here](https://www.mono-project.com/download/stable/#download-lin-ubuntu). Mono is **not** required if you target .NET Core 3.1, .NET 5 or .NET 6 on Linux.
+ * Puppeteer-Sharp comes in two flavors: a NetStandard 2.0 library for .NET Framework 4.6.1 and .NET Core 2.0 or greater and a .NET 8 version.
  * If you have issues running Chrome on Linux, the Puppeteer repo has a [great troubleshooting guide](https://github.com/GoogleChrome/puppeteer/blob/master/docs/troubleshooting.md).
 
-# Monthly reports
- * [August 2019](http://www.hardkoded.com/blog/puppeteer-sharp-monthly-aug-2019)
- * [July 2019](http://www.hardkoded.com/blog/puppeteer-sharp-monthly-jul-2019)
- * [June 2019](http://www.hardkoded.com/blog/puppeteer-sharp-monthly-jun-2019)
- * [May 2019](http://www.hardkoded.com/blog/puppeteer-sharp-monthly-may-2019)
- * [April 2019](http://www.hardkoded.com/blog/puppeteer-sharp-monthly-apr-2019)
- * [March 2019](http://www.hardkoded.com/blog/puppeteer-sharp-monthly-mar-2019)
- * [February 2019](http://www.hardkoded.com/blog/puppeteer-sharp-monthly-feb-2019)
- * [January 2019](http://www.hardkoded.com/blog/puppeteer-sharp-monthly-jan-2019)
-
 # Useful links
 
 * [GitHub-Repo](https://github.com/hardkoded/puppeteer-sharp)

diff --git a/docfx_project/toc.yml b/docfx_project/toc.yml
@@ -1,6 +1,6 @@
 - name: Api Documentation
   href: api/
   homepage: api/index.md
-- name: Examples
-  href: examples/
-  homepage: examples/index.md
+- name: Docs
+  href: docs/
+  homepage: docs/index.md
diff --git a/lib/PuppeteerSharp.AspNetFramework/AspNetWebSocketTransport.cs b/lib/PuppeteerSharp.AspNetFramework/AspNetWebSocketTransport.cs
@@ -9,8 +9,6 @@ namespace PuppeteerSharp.AspNetFramework
 {
     public class AspNetWebSocketTransport : WebSocketTransport
     {
-        #region Static fields
-
         /// <summary>
         /// Gets a <see cref="TransportFactory"/> that creates <see cref="AspNetWebSocketTransport"/> instances.
         /// </summary>
@@ -22,10 +20,6 @@ public class AspNetWebSocketTransport : WebSocketTransport
         /// </summary>
         public static readonly TransportTaskScheduler AspNetTransportScheduler = ScheduleBackgroundTask;
 
-        #endregion
-
-        #region Static methods
-
         private static async Task<IConnectionTransport> CreateAspNetTransport(Uri url, IConnectionOptions connectionOptions, CancellationToken cancellationToken)
         {
             var webSocketFactory = connectionOptions.WebSocketFactory ?? DefaultWebSocketFactory;
@@ -40,15 +34,9 @@ Task ExecuteAsync(CancellationToken hostingCancellationToken)
             HostingEnvironment.QueueBackgroundWorkItem(ExecuteAsync);
         }
 
-        #endregion
-
-        #region Constructor(s)
-
         /// <inheritdoc />
         public AspNetWebSocketTransport(WebSocket client, bool queueRequests)
             : base(client, AspNetTransportScheduler, queueRequests)
         { }
-
-        #endregion
     }
 }
diff --git a/lib/PuppeteerSharp.Tests/Browsers/Chrome/ChromeDataTests.cs b/lib/PuppeteerSharp.Tests/Browsers/Chrome/ChromeDataTests.cs
@@ -11,7 +11,7 @@ public class ChromeDataTests
     {
         public async Task ReuseChromeExample()
         {
-            #region ReuseChromeExample
+            #region reusechrome_example
             var downloadPath = "/Users/dario/chrome";
             var browserFetcherOptions = new BrowserFetcherOptions { Path = downloadPath };
             var browserFetcher = new BrowserFetcher(browserFetcherOptions);
@@ -21,7 +21,7 @@ public async Task ReuseChromeExample()
 
         public async Task Usage()
         {
-            #region CustomVersionsExample
+            #region customversions_example
             Console.WriteLine("Downloading browsers");
 
             var browserFetcher = new BrowserFetcher(SupportedBrowser.Chrome);

diff --git a/lib/PuppeteerSharp.Tests/DeviceRequestPromptTests/WaitForDevicePromptTests.cs b/lib/PuppeteerSharp.Tests/DeviceRequestPromptTests/WaitForDevicePromptTests.cs
@@ -10,7 +10,7 @@ public class WaitForDevicePromptTests : PuppeteerPageBaseTest
     {
         public async Task Usage()
         {
-            #region DeviceRequestPromptUsage
+            #region devicerequestprompt_usage
             var promptTask = Page.WaitForDevicePromptAsync();
             await Task.WhenAll(
                 promptTask,
@@ -25,7 +25,7 @@ await devicePrompt.WaitForDeviceAsync(device => device.Name.Contains("My Device"
 
         public async Task PageUsage()
         {
-            #region IPageWaitForDevicePromptAsyncUsage
+            #region ipagewaitfordevicepromptasync_usage
             var promptTask = Page.WaitForDevicePromptAsync();
             await Task.WhenAll(
                 promptTask,
@@ -41,7 +41,7 @@ await devicePrompt.WaitForDeviceAsync(device => device.Name.Contains("My Device"
         public async Task FrameUsage()
         {
             var frame = Page.MainFrame;
-            #region IFrameWaitForDevicePromptAsyncUsage
+            #region iframewaitfordevicepromptasync_usage
             var promptTask = frame.WaitForDevicePromptAsync();
             await Task.WhenAll(
                 promptTask,