Teach waitForSelector to return null (#932)

Author: kblok

lib/PuppeteerSharp.Tests/FrameTests/WaitForSelectorTests.cs

@@ -172,6 +172,13 @@ public async Task HiddenShouldWaitForRemoval()
             Assert.True(divRemoved);
         }
 
+        [Fact]
+        public async Task ShouldReturnNullIfWaitingToHideNonExistingElement()
+        {
+            var handle = await Page.WaitForSelectorAsync("non-existing", new WaitForSelectorOptions { Hidden = true });
+            Assert.Null(handle);
+        }
+
         [Fact]
         public async Task ShouldRespectTimeout()
         {
@@ -209,5 +216,13 @@ public async Task ShouldReturnTheElementHandle()
             await Page.SetContentAsync("<div class='zombo'>anything</div>");
             Assert.Equal("anything", await Page.EvaluateFunctionAsync<string>("x => x.textContent", await waitForSelector));
         }
+
+        [Fact]
+        public async Task ShouldHaveCorrectStackTraceForTimeout()
+        {
+            var exception = await Assert.ThrowsAsync<WaitTaskTimeoutException>(async ()
+                => await Page.WaitForSelectorAsync(".zombo", new WaitForSelectorOptions { Timeout = 10 }));
+            Assert.Contains("WaitForSelectorTests", exception.StackTrace);
+        }
     }
 }

lib/PuppeteerSharp/DOMWorld.cs

@@ -407,7 +407,13 @@ function hasVisibleBoundingBox() {
                     options.Visible,
                     options.Hidden
                 }).Task.ConfigureAwait(false);
-            return handle as ElementHandle;
+
+            if (!(handle is ElementHandle elementHandle))
+            {
+                await handle?.DisposeAsync();
+                return null;
+            }
+            return elementHandle;
         }
     }
 }

lib/PuppeteerSharp/Frame.cs

@@ -241,7 +241,8 @@ public Task<Response> GoToAsync(string url, int? timeout = null, WaitUntilNaviga
         /// </summary>
         /// <param name="selector">A selector of an element to wait for</param>
         /// <param name="options">Optional waiting parameters</param>
-        /// <returns>A task that resolves when element specified by selector string is added to DOM</returns>
+        /// <returns>A task that resolves when element specified by selector string is added to DOM.
+        /// Resolves to `null` if waiting for `hidden: true` and selector is not found in DOM.</returns>
         /// <seealso cref="WaitForXPathAsync(string, WaitForSelectorOptions)"/>
         /// <seealso cref="Page.WaitForSelectorAsync(string, WaitForSelectorOptions)"/>
         /// <exception cref="WaitTaskTimeoutException">If timeout occurred.</exception>
@@ -253,7 +254,8 @@ public Task<ElementHandle> WaitForSelectorAsync(string selector, WaitForSelector
         /// </summary>
         /// <param name="xpath">A xpath selector of an element to wait for</param>
         /// <param name="options">Optional waiting parameters</param>
-        /// <returns>A task that resolves when element specified by selector string is added to DOM</returns>
+        /// <returns>A task which resolves when element specified by xpath string is added to DOM. 
+        /// Resolves to `null` if waiting for `hidden: true` and xpath is not found in DOM.</returns>
         /// <example>
         /// <code>
         /// <![CDATA[

lib/PuppeteerSharp/Page.cs

@@ -1310,7 +1310,8 @@ public Task<JSHandle> WaitForExpressionAsync(string script, WaitForFunctionOptio
         /// </summary>
         /// <param name="selector">A selector of an element to wait for</param>
         /// <param name="options">Optional waiting parameters</param>
-        /// <returns>A task that resolves when element specified by selector string is added to DOM</returns>
+        /// <returns>A task that resolves when element specified by selector string is added to DOM.
+        /// Resolves to `null` if waiting for `hidden: true` and selector is not found in DOM.</returns>
         /// <seealso cref="WaitForXPathAsync(string, WaitForSelectorOptions)"/>
         /// <seealso cref="Frame.WaitForSelectorAsync(string, WaitForSelectorOptions)"/>
         public Task<ElementHandle> WaitForSelectorAsync(string selector, WaitForSelectorOptions options = null)
@@ -1321,7 +1322,8 @@ public Task<ElementHandle> WaitForSelectorAsync(string selector, WaitForSelector
         /// </summary>
         /// <param name="xpath">A xpath selector of an element to wait for</param>
         /// <param name="options">Optional waiting parameters</param>
-        /// <returns>A task that resolves when element specified by selector string is added to DOM</returns>
+        /// <returns>A task which resolves when element specified by xpath string is added to DOM. 
+        /// Resolves to `null` if waiting for `hidden: true` and xpath is not found in DOM.</returns>
         /// <example>
         /// <code>
         /// <![CDATA[