docs: How to download different browsers (#2383)

* Add downloads example * Add docs
hardkoded · Dec 20, 2023 · 2ebe57f · 2ebe57f
1 parent a867914
commit 2ebe57f
Show file tree

Hide file tree

Showing 5 changed files with 105 additions and 7 deletions.
diff --git a/.github/workflows/on-push-do-docs.yml b/.github/workflows/on-push-do-docs.yml
@@ -9,7 +9,7 @@ jobs:
     - name: Run MarkdownSnippets
       run: |
         dotnet tool install --global MarkdownSnippets.Tool
-        mdsnippets ${GITHUB_WORKSPACE}
+        mdsnippets ${GITHUB_WORKSPACE} --url-prefix https://github.com/hardkoded/puppeteer-sharp/blob/master
       shell: bash
     - name: Push changes
       run: |
@@ -19,4 +19,4 @@ jobs:
         remote="https://${GITHUB_ACTOR}:${{secrets.GITHUB_TOKEN}}@github.com/${GITHUB_REPOSITORY}.git"
         branch="${GITHUB_REF:11}"
         git push "${remote}" ${branch} || echo "nothing to push"
-      shell: bash
+      shell: bash
diff --git a/README.md b/README.md
@@ -56,7 +56,7 @@ await using var page = await browser.NewPageAsync();
 await page.GoToAsync("http://www.google.com");
 await page.ScreenshotAsync(outputFile);
 ```
-<sup><a href='/lib/PuppeteerSharp.Tests/ScreenshotTests/PageScreenshotTests.cs#L61-L69' 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#L61-L69' title='Snippet source file'>snippet source</a> | <a href='#snippet-screenshotasync' title='Start of snippet'>anchor</a></sup>
 <!-- endSnippet -->
 
 You can also change the view port before generating the screenshot
@@ -70,7 +70,7 @@ await Page.SetViewportAsync(new ViewPortOptions
     Height = 500
 });
 ```
-<sup><a href='/lib/PuppeteerSharp.Tests/ScreenshotTests/ElementHandleScreenshotTests.cs#L19-L25' 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#L19-L25' title='Snippet source file'>snippet source</a> | <a href='#snippet-setviewportasync' title='Start of snippet'>anchor</a></sup>
 <!-- endSnippet -->
 
 ### Generate PDF files
@@ -86,7 +86,7 @@ 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='/lib/PuppeteerSharp.Tests/PageTests/PdfTests.cs#L28-L38' 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#L28-L38' title='Snippet source file'>snippet source</a> | <a href='#snippet-pdfasync' title='Start of snippet'>anchor</a></sup>
 <!-- endSnippet -->
 
 ### Inject HTML
@@ -98,7 +98,7 @@ await using var page = await browser.NewPageAsync();
 await page.SetContentAsync("<div>My Receipt</div>");
 var result = await page.GetContentAsync();
 ```
-<sup><a href='/lib/PuppeteerSharp.Tests/PageTests/SetContentTests.cs#L19-L25' 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#L19-L25' title='Snippet source file'>snippet source</a> | <a href='#snippet-setcontentasync' title='Start of snippet'>anchor</a></sup>
 <!-- endSnippet -->
 
 ### Evaluate Javascript
@@ -111,7 +111,7 @@ var seven = await page.EvaluateExpressionAsync<int>("4 + 3");
 var someObject = await page.EvaluateFunctionAsync<dynamic>("(value) => ({a: value})", 5);
 Console.WriteLine(someObject.a);
 ```
-<sup><a href='/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' title='Start of snippet'>anchor</a></sup>
 <!-- endSnippet -->
 
 ### Wait For Selector

diff --git a/docfx_project/examples/DownloadFetcher.Download.md b/docfx_project/examples/DownloadFetcher.Download.md
@@ -0,0 +1,56 @@
+# How to test a Chrome Extension
+_Contributors: [Dario Kondratiuk](https://github.com/kblok)_
+
+## Problem
+
+You need to download an use an specific browser version.
+
+## Solution
+
+Thank to [Google for testing](https://developer.chrome.com/blog/chrome-for-testing). Now finding and downloading a specific version of Chrome is easy.
+
+You will find the available versions [here](https://googlechromelabs.github.io/chrome-for-testing/known-good-versions.json).
+Once you have the version you want, you can download it using the `BrowserFetcher` class.
+
+```cs
+<!-- snippet: CustomVersionsExample -->
+<a id='snippet-customversionsexample'></a>
+```cs
+Console.WriteLine("Downloading browsers");
+
+using var browserFetcher = new BrowserFetcher(SupportedBrowser.Chrome);
+var chrome118 = await browserFetcher.DownloadAsync("118.0.5993.70");
+var chrome119 = await browserFetcher.DownloadAsync("119.0.5997.0");
+
+Console.WriteLine("Navigating");
+await using (var browser = await Puppeteer.LaunchAsync(new()
+             {
+                 ExecutablePath = chrome118.GetExecutablePath(),
+             }))
+{
+    await using var page = await browser.NewPageAsync();
+    await page.GoToAsync("https://www.whatismybrowser.com/");
+
+    Console.WriteLine("Generating PDF");
+    await page.PdfAsync(Path.Combine(Directory.GetCurrentDirectory(), "118.pdf"));
+
+    Console.WriteLine("Export completed");
+}
+
+await using (var browser = await Puppeteer.LaunchAsync(new()
+             {
+                 ExecutablePath = chrome119.GetExecutablePath(),
+             }))
+{
+    await using var page = await browser.NewPageAsync();
+    await page.GoToAsync("https://www.whatismybrowser.com/");
+
+    Console.WriteLine("Generating PDF");
+    await page.PdfAsync(Path.Combine(Directory.GetCurrentDirectory(), "119.pdf"));
+
+    Console.WriteLine("Export completed");
+}
+```
+<sup><a href='https://github.com/hardkoded/puppeteer-sharp/blob/master/lib/PuppeteerSharp.Tests/Browsers/Chrome/ChromeDataTests.cs#L15-L50' title='Snippet source file'>snippet source</a> | <a href='#snippet-customversionsexample' title='Start of snippet'>anchor</a></sup>
+<!-- endSnippet -->
+```
diff --git a/docfx_project/examples/toc.yml b/docfx_project/examples/toc.yml
@@ -16,6 +16,8 @@
       href: Page.WaitForFunctionAsync.md
     - name: How to log network requests
       href: Page.Request.md
+    - name: How to download an specific browser
+      href: DownloadFetcher.Download.md
 - name: Advanced
   items:
     - name: How to log CDP communication

diff --git a/lib/PuppeteerSharp.Tests/Browsers/Chrome/ChromeDataTests.cs b/lib/PuppeteerSharp.Tests/Browsers/Chrome/ChromeDataTests.cs
@@ -10,6 +10,46 @@ namespace PuppeteerSharp.Tests.Browsers.Chrome
 {
     public class ChromeDataTests
     {
+        public async Task Usage()
+        {
+            #region CustomVersionsExample
+            Console.WriteLine("Downloading browsers");
+
+            using var browserFetcher = new BrowserFetcher(SupportedBrowser.Chrome);
+            var chrome118 = await browserFetcher.DownloadAsync("118.0.5993.70");
+            var chrome119 = await browserFetcher.DownloadAsync("119.0.5997.0");
+
+            Console.WriteLine("Navigating");
+            await using (var browser = await Puppeteer.LaunchAsync(new()
+                         {
+                             ExecutablePath = chrome118.GetExecutablePath(),
+                         }))
+            {
+                await using var page = await browser.NewPageAsync();
+                await page.GoToAsync("https://www.whatismybrowser.com/");
+
+                Console.WriteLine("Generating PDF");
+                await page.PdfAsync(Path.Combine(Directory.GetCurrentDirectory(), "118.pdf"));
+
+                Console.WriteLine("Export completed");
+            }
+
+            await using (var browser = await Puppeteer.LaunchAsync(new()
+                         {
+                             ExecutablePath = chrome119.GetExecutablePath(),
+                         }))
+            {
+                await using var page = await browser.NewPageAsync();
+                await page.GoToAsync("https://www.whatismybrowser.com/");
+
+                Console.WriteLine("Generating PDF");
+                await page.PdfAsync(Path.Combine(Directory.GetCurrentDirectory(), "119.pdf"));
+
+                Console.WriteLine("Export completed");
+            }
+            #endregion
+        }
+
         [PuppeteerTest("chrome-data.spec.ts", "Chrome", "should resolve download URLs")]
         public void ShouldResolveDownloadUrls()
         {