Implement Puppeteer.ConnectAsync (#137)

Author: cdroulers

lib/PuppeteerSharp.Tests/FrameUtils.cs

@@ -1,4 +1,5 @@
 using System;
+using System.Text.RegularExpressions;
 using System.Threading.Tasks;
 
 namespace PuppeteerSharp.Tests
@@ -15,5 +16,16 @@ await page.EvaluateFunctionAsync(@"(frameId, url) => {
               return new Promise(x => frame.onload = x);
             }", frameId, url);
         }
+
+        public static string DumpFrames(Frame frame, string indentation = "")
+        {
+            var result = indentation + Regex.Replace(frame.Url, @":\d{4}", ":<PORT>");
+            foreach (var child in frame.ChildFrames)
+            {
+                result += Environment.NewLine + DumpFrames(child, "    " + indentation);
+            }
+
+            return result;
+        }
     }
 }

lib/PuppeteerSharp.Tests/Puppeteer/PuppeteerConnectTests.cs

@@ -0,0 +1,57 @@
+using System.Linq;
+using System.Threading.Tasks;
+using Xunit;
+
+namespace PuppeteerSharp.Tests.Puppeteer
+{
+    [Collection("PuppeteerLoaderFixture collection")]
+    public class PuppeteerConnectTests : PuppeteerBaseTest
+    {
+        [Fact]
+        public async Task ShouldBeAbleToConnectMultipleTimesToSameBrowser()
+        {
+            var options = new ConnectOptions()
+            {
+                BrowserWSEndpoint = Browser.WebSocketEndpoint
+            };
+            var browser = await PuppeteerSharp.Puppeteer.ConnectAsync(options);
+            using (var page = await browser.NewPageAsync())
+            {
+                var response = await page.EvaluateExpressionAsync<int>("7 * 8");
+                Assert.Equal(response, 56);
+            }
+
+            using (var originalPage = await Browser.NewPageAsync())
+            {
+                var response = await originalPage.EvaluateExpressionAsync<int>("7 * 6");
+                Assert.Equal(response, 42);
+            }
+        }
+
+        [Fact]
+        public async Task ShouldBeAbleToReconnectToADisconnectedBrowser()
+        {
+            var options = new ConnectOptions()
+            {
+                BrowserWSEndpoint = Browser.WebSocketEndpoint
+            };
+
+            var url = TestConstants.CrossProcessHttpPrefix + "/frames/frame.html";
+            var page = await Browser.NewPageAsync();
+            await page.GoToAsync(url);
+
+            Browser.Disconnect();
+
+            using (var browser = await PuppeteerSharp.Puppeteer.ConnectAsync(options))
+            {
+                var pages = (await browser.Pages()).ToList();
+                var restoredPage = pages.FirstOrDefault(x => x.Url == url);
+                Assert.NotNull(restoredPage);
+                var frameDump = FrameUtils.DumpFrames(restoredPage.MainFrame);
+                Assert.Equal(@"http://127.0.0.1:<PORT>/frames/frame.html", frameDump);
+                var response = await restoredPage.EvaluateExpressionAsync<int>("7 * 8");
+                Assert.Equal(response, 56);
+            }
+        }
+    }
+}

lib/PuppeteerSharp.Tests/PuppeteerSharp.Tests.csproj

@@ -15,7 +15,6 @@
   </ItemGroup>
 
   <ItemGroup>
-    <Folder Include="Puppeteer\" />
     <Folder Include="Issues\" />
   </ItemGroup>
 

lib/PuppeteerSharp/Browser.cs

@@ -1,13 +1,14 @@
 using System;
 using System.Collections.Generic;
 using System.Dynamic;
+using System.Linq;
 using System.Threading.Tasks;
 
 namespace PuppeteerSharp
 {
     public class Browser : IDisposable
     {
-        public Browser(Connection connection, LaunchOptions options, Func<Task> closeCallBack)
+        public Browser(Connection connection, IBrowserOptions options, Func<Task> closeCallBack)
         {
             Connection = connection;
             IgnoreHTTPSErrors = options.IgnoreHTTPSErrors;
@@ -69,6 +70,9 @@ public async Task<Page> NewPageAsync()
             return await target.Page();
         }
 
+        public async Task<IEnumerable<Page>> Pages()
+            => (await Task.WhenAll(this._targets.Select(x => x.Value.Page()))).Where(x => x != null);
+
         internal void ChangeTarget(TargetInfo targetInfo)
         {
             TargetChanged?.Invoke(this, new TargetChangedArgs()
@@ -83,6 +87,8 @@ public async Task<string> GetVersionAsync()
             return version.product.ToString();
         }
 
+        public void Disconnect() => Connection.Dispose();
+
         public async Task CloseAsync()
         {
             if (IsClosed)
@@ -93,7 +99,7 @@ public async Task CloseAsync()
             IsClosed = true;
 
             await _closeCallBack();
-            Connection.Dispose();
+            Disconnect();
             Closed?.Invoke(this, new EventArgs());
         }
 
@@ -166,7 +172,7 @@ private async Task CreateTarget(MessageEventArgs args)
 
         }
 
-        internal static async Task<Browser> CreateAsync(Connection connection, LaunchOptions options,
+        internal static async Task<Browser> CreateAsync(Connection connection, IBrowserOptions options,
                                                         Func<Task> closeCallBack)
         {
             var browser = new Browser(connection, options, closeCallBack);

lib/PuppeteerSharp/ConnectOptions.cs

@@ -0,0 +1,33 @@
+namespace PuppeteerSharp
+{
+    /// <summary>
+    /// Options for connecting to an existing browser.
+    /// </summary>
+    public class ConnectOptions : IBrowserOptions
+    {
+        /// <summary>
+        /// Whether to ignore HTTPS errors during navigation. Defaults to false.
+        /// </summary>
+        public bool IgnoreHTTPSErrors { get; set; }
+
+        /// <summary>
+        /// If set to true, sets Headless = false, otherwise, enables automation.
+        /// </summary>
+        public bool AppMode { get; set; }
+
+        /// <summary>
+        /// A browser websocket endpoint to connect to.
+        /// </summary>
+        public string BrowserWSEndpoint { get; set; }
+
+        /// <summary>
+        /// Slows down Puppeteer operations by the specified amount of milliseconds. Useful so that you can see what is going on.
+        /// </summary>
+        public int SlowMo { get; set; }
+
+        /// <summary>
+        /// Keep alive value.
+        /// </summary>
+        public int KeepAliveInterval { get; set; } = 30;
+    }
+}

lib/PuppeteerSharp/IBrowserOptions.cs

@@ -0,0 +1,15 @@
+namespace PuppeteerSharp
+{
+    public interface IBrowserOptions
+    {
+        /// <summary>
+        /// Whether to ignore HTTPS errors during navigation. Defaults to false.
+        /// </summary>
+        bool IgnoreHTTPSErrors { get; }
+
+        /// <summary>
+        /// If set to true, sets Headless = false, otherwise, enables automation.
+        /// </summary>
+        bool AppMode { get; }
+    }
+}

lib/PuppeteerSharp/LaunchOptions.cs

@@ -3,32 +3,74 @@
 
 namespace PuppeteerSharp
 {
-    public class LaunchOptions
+    /// <summary>
+    /// Options for launching the Chrome/ium browser.
+    /// </summary>
+    public class LaunchOptions : IBrowserOptions
     {
+        /// <summary>
+        /// Whether to ignore HTTPS errors during navigation. Defaults to false.
+        /// </summary>
+        public bool IgnoreHTTPSErrors { get; set; }
+
+        /// <summary>
+        /// If set to true, sets Headless = false, otherwise, enables automation.
+        /// </summary>
         public bool AppMode { get; set; }
 
-        public bool IgnoreHTTPSErrors { get; set; }
-        
+        /// <summary>
+        /// Whether to run browser in headless mode. Defaults to true unless the devtools option is true.
+        /// </summary>
         public bool Headless { get; set; } = true;
 
+        /// <summary>
+        /// Path to a Chromium or Chrome executable to run instead of bundled Chromium. If executablePath is a relative path, then it is resolved relative to current working directory.
+        /// </summary>
         public string ExecutablePath { get; set; }
 
+        /// <summary>
+        /// Slows down Puppeteer operations by the specified amount of milliseconds. Useful so that you can see what is going on.
+        /// </summary>
         public int SlowMo { get; set; }
 
+        /// <summary>
+        /// Additional arguments to pass to the browser instance. List of Chromium flags can be found <a href="http://peter.sh/experiments/chromium-command-line-switches/">here</a>.
+        /// </summary>
         public string[] Args { get; set; } = Array.Empty<string>();
-        
+
+        /// <summary>
+        /// Maximum time in milliseconds to wait for the browser instance to start. Defaults to 30000 (30 seconds). Pass 0 to disable timeout.
+        /// </summary>
         public int Timeout { get; set; } = 30_000;
 
+        /// <summary>
+        ///  Whether to pipe browser process stdout and stderr into process.stdout and process.stderr. Defaults to false.
+        /// </summary>
         public bool DumpIO { get; set; }
 
+        /// <summary>
+        /// Path to a User Data Directory.
+        /// </summary>
         public string UserDataDir { get; set; }
 
+        /// <summary>
+        /// Specify environment variables that will be visible to browser. Defaults to Environment variables.
+        /// </summary>
         public IDictionary<string, string> Env { get; } = new Dictionary<string, string>();
 
+        /// <summary>
+        /// Whether to auto-open DevTools panel for each tab. If this option is true, the headless option will be set false.
+        /// </summary>
         public bool Devtools { get; set; }
 
+        /// <summary>
+        /// Keep alive value.
+        /// </summary>
         public int KeepAliveInterval { get; set; } = 30;
 
+        /// <summary>
+        /// Logs process counts after launching chrome and after exiting.
+        /// </summary>
         public bool LogProcess { get; set; }
     }
 }

lib/PuppeteerSharp/Launcher.cs

@@ -60,6 +60,17 @@ public Launcher()
         }
 
         #region Public methods
+        /// <summary>
+        /// The method launches a browser instance with given arguments. The browser will be closed when the Browser is disposed.
+        /// </summary>
+        /// <param name="options">Options for launching Chrome</param>
+        /// <param name="chromiumRevision">The revision of Chrome to launch.</param>
+        /// <returns>A connected browser.</returns>
+        /// <remarks>
+        /// See <a href="https://www.howtogeek.com/202825/what%E2%80%99s-the-difference-between-chromium-and-chrome/">this article</a>
+        /// for a description of the differences between Chromium and Chrome.
+        /// <a href="https://chromium.googlesource.com/chromium/src/+/lkcr/docs/chromium_browser_vs_google_chrome.md">This article</a> describes some differences for Linux users.
+        /// </remarks>
         public async Task<Browser> LaunchAsync(LaunchOptions options, int chromiumRevision)
         {
             var chromeArguments = new List<string>(DefaultArgs);
@@ -170,6 +181,28 @@ public async Task<Browser> LaunchAsync(LaunchOptions options, int chromiumRevisi
 
         }
 
+        /// <summary>
+        /// Attaches Puppeteer to an existing Chromium instance. The browser will be closed when the Browser is disposed.
+        /// </summary>
+        /// <param name="options">Options for connecting.</param>
+        /// <returns>A connected browser.</returns>
+        public async Task<Browser> ConnectAsync(ConnectOptions options)
+        {
+            try
+            {
+                var connectionDelay = options.SlowMo;
+                var keepAliveInterval = options.KeepAliveInterval;
+
+                _connection = await Connection.Create(options.BrowserWSEndpoint, connectionDelay, keepAliveInterval);
+
+                return await Browser.CreateAsync(_connection, options, () => _connection.SendAsync("Browser.close", null));
+            }
+            catch (Exception ex)
+            {
+                throw new Exception("Failed to create connection", ex);
+            }
+        }
+
         public async Task TryDeleteUserDataDir(int times = 10, TimeSpan? delay = null)
         {
             if (!IsChromeClosed)
@@ -338,7 +371,6 @@ private async Task KillChrome()
             }
 
             await _waitForChromeToClose.Task;
-
         }
 
         private void ForceKillChrome()
@@ -357,7 +389,6 @@ private void ForceKillChrome()
             }
         }
 
-
         private static void SetEnvVariables(IDictionary<string, string> environment, IDictionary<string, string> customEnv,
                                             IDictionary realEnv)
         {

lib/PuppeteerSharp/Page.cs

@@ -1,18 +1,19 @@
 using System;
-using System.Linq;
 using System.Collections.Generic;
-using System.Threading.Tasks;
-using PuppeteerSharp.Input;
-using PuppeteerSharp.Helpers;
-using System.IO;
+using System.Diagnostics;
+using System.Dynamic;
 using System.Globalization;
+using System.IO;
+using System.Linq;
+using System.Threading.Tasks;
 using Newtonsoft.Json.Linq;
-using System.Dynamic;
+using PuppeteerSharp.Helpers;
+using PuppeteerSharp.Input;
 using PuppeteerSharp.Messaging;
-using System.Threading;
 
 namespace PuppeteerSharp
 {
+    [DebuggerDisplay("Page {Url}")]
     public class Page : IDisposable
     {
         public int DefaultNavigationTimeout { get; set; } = 30000;