Added an API to execute native PhantomJS code in .NET

livioc · jimevans · commit 72760b0c3283 · 2014-02-05T11:16:23.000-05:00
Fixes issue #6949.
diff --git a/common/src/web/injectableContent.html b/common/src/web/injectableContent.html
@@ -0,0 +1,22 @@
+<html>
+  <head>
+    <title>random numbers</title>
+    <script>
+      function display() {
+        document.getElementById('numbers').textContent = numbers.join(' ');
+      }
+    </script>
+  </head>
+  <body onload="display()">
+    <p>Some random numbers between 0 and 100:</p>
+
+    <!-- Placeholder for the list of random numbers -->
+    <p id="numbers"></p>
+    <script>
+      numbers = [];
+      while (numbers.length < 100) {
+        numbers.push(Math.round(Math.random() * 100));
+      }
+    </script>
+  </body>
+</html>
diff --git a/dotnet/CHANGELOG b/dotnet/CHANGELOG
@@ -39,6 +39,9 @@ v2.40.0
    collisions in random number generation encountered when using the .NET
    Random class, particularly in different processes. GUIDs are used as their
    generation in the .NET Framework is optimized for performance.
+ * Updated .NET PhantomJS driver to be able to execute code in the PhantomJS
+   context. This allows the user to execute PhantomJS-specific commands using
+   the PhantomJS JavaScript API.
  * Updated .NET bindings to use webdriver.json for default Firefox profile.    
    Other language bindings have been using a common JSON file containing the
    default profile setting for the anonymous Firefox profile used by the
diff --git a/dotnet/src/webdriver/PhantomJS/PhantomJSDriver.cs b/dotnet/src/webdriver/PhantomJS/PhantomJSDriver.cs
@@ -21,6 +21,7 @@
 using System.Globalization;
 using System.Text;
 using OpenQA.Selenium.Remote;
+using OpenQA.Selenium.Internal;
 
 namespace OpenQA.Selenium.PhantomJS
 {
@@ -64,6 +65,11 @@ namespace OpenQA.Selenium.PhantomJS
     /// </example>
     public class PhantomJSDriver : RemoteWebDriver, ITakesScreenshot
     {
+        /// <summary>
+        /// Command name of the PhantomJS-specific command to execute native script in PhantomJS.
+        /// </summary>
+        private const string CommandExecutePhantomScript = "executePhantomScript";
+
         /// <summary>
         /// Initializes a new instance of the <see cref="PhantomJSDriver"/> class.
         /// </summary>
@@ -143,6 +149,9 @@ public PhantomJSDriver(PhantomJSDriverService service, PhantomJSOptions options)
         public PhantomJSDriver(PhantomJSDriverService service, PhantomJSOptions options, TimeSpan commandTimeout)
             : base(new DriverServiceCommandExecutor(service, commandTimeout, false), options.ToCapabilities())
         {
+            // Add the custom commandInfo of PhantomJSDriver
+            CommandInfo commandInfo = new CommandInfo(CommandInfo.PostCommand, "/session/{sessionId}/phantom/execute");
+            CommandInfoRepository.Instance.TryAddAdditionalCommand(CommandExecutePhantomScript, commandInfo);
         }
 
         /// <summary>
@@ -161,6 +170,39 @@ public override IFileDetector FileDetector
             set { }
         }
 
+        /// <summary>
+        /// Execute a PhantomJS script fragment. Provides extra functionality not found in WebDriver
+        /// but available in PhantomJS.
+        /// </summary>
+        /// <param name="script">The fragment of PhantomJS JavaScript to execute.</param>
+        /// <param name="args">List of arguments to pass to the function that the script is wrapped in.
+        /// These can accessed in the script as 'arguments[0]', 'arguments[1]','arguments[2]', etc
+        /// </param>
+        /// <returns>The result of the evaluation.</returns>
+        /// <remarks>
+        /// <para>
+        /// See the <a href="https://github.com/ariya/phantomjs/wiki/API-Reference">PhantomJS API</a>
+        /// for details on what is available.
+        /// </para>
+        /// <para>
+        /// A 'page' variable pointing to currently selected page is available for use.
+        /// If there is no page yet, one is created.
+        /// </para>
+        /// <para>
+        /// When overriding any callbacks be sure to wrap in a try/catch block, as failures
+        /// may cause future WebDriver calls to fail.
+        /// </para>
+        /// <para>
+        /// Certain callbacks are used by GhostDriver (the PhantomJS WebDriver implementation)
+        /// already. Overriding these may cause the script to fail. It's a good idea to check
+        /// for existing callbacks before overriding.
+        /// </para>
+        /// </remarks>
+        public object ExecutePhantomJS(string script, params object[] args)
+        {
+            return this.ExecuteScriptCommand(script, CommandExecutePhantomScript, args);
+        }
+
         #region ITakesScreenshot Members
         /// <summary>
         /// Gets a <see cref="Screenshot"/> object representing the image of the page on the screen.
diff --git a/dotnet/src/webdriver/Remote/CommandInfoRepository.cs b/dotnet/src/webdriver/Remote/CommandInfoRepository.cs
@@ -24,14 +24,19 @@ namespace OpenQA.Selenium.Remote
 {
     /// <summary>
     /// Holds the information about all commands specified by the JSON wire protocol.
+    /// This class cannot be inherited, as it is intended to be a singleton, and 
+    /// allowing subclasses introduces the possibility of multiple instances.
     /// </summary>
-    public class CommandInfoRepository
+    public sealed class CommandInfoRepository
     {
         #region Private members
-        private static object lockObject = new object();
-        private static CommandInfoRepository collectionInstance;
+        private static readonly object lockObject = new object();
 
-        private Dictionary<string, CommandInfo> commandDictionary;
+        // Note this is marked volatile to force the runtime to allow
+        // serialized access to the value.
+        private static volatile CommandInfoRepository collectionInstance;
+
+        private readonly Dictionary<string, CommandInfo> commandDictionary;
         #endregion
 
         #region Constructor
@@ -53,11 +58,16 @@ public static CommandInfoRepository Instance
         {
             get
             {
-                lock (lockObject)
+                // This is an implementation using double-checked locking as described
+                // at http://msdn.microsoft.com/en-us/library/ff650316.aspx
+                if (collectionInstance == null)
                 {
-                    if (collectionInstance == null)
+                    lock (lockObject)
                     {
-                        collectionInstance = new CommandInfoRepository();
+                        if (collectionInstance == null)
+                        {
+                            collectionInstance = new CommandInfoRepository();
+                        }
                     }
                 }
 
@@ -82,6 +92,38 @@ public CommandInfo GetCommandInfo(string commandName)
 
             return toReturn;
         }
+
+        /// <summary>
+        /// Tries the add an additional command to the list of known commands.
+        /// </summary>
+        /// <param name="commandName">Name of the command.</param>
+        /// <param name="commandInfo">The command information.</param>
+        /// <returns><see langword="true"/> if the new command has been added successfully; otherwise, <see langword="false"/>.</returns>
+        /// <remarks>
+        /// This method is used by WebDriver implementations to add additional custom driver-specific commands.
+        /// This method will not overwrite existing commands for a specific name.
+        /// </remarks>
+        internal bool TryAddAdditionalCommand(string commandName, CommandInfo commandInfo)
+        {
+            if (string.IsNullOrEmpty(commandName))
+            {
+                throw new ArgumentNullException("commandName", "The name of the command cannot be null or the empty string.");
+            }
+
+            if (commandInfo == null)
+            {
+                throw new ArgumentNullException("commandInfo", "The command information object cannot be null.");
+            }
+
+            if (this.commandDictionary.ContainsKey(commandName))
+            {
+                return false;
+            }
+
+            this.commandDictionary.Add(commandName, commandInfo);
+            return true;
+        }
+
         #endregion
 
         #region Private support methods
diff --git a/dotnet/src/webdriver/Remote/RemoteWebDriver.cs b/dotnet/src/webdriver/Remote/RemoteWebDriver.cs
@@ -423,7 +423,7 @@ public ITargetLocator SwitchTo()
         /// <returns>The value returned by the script.</returns>
         public object ExecuteScript(string script, params object[] args)
         {
-            return this.ExecuteScriptInternal(script, false, args);
+            return this.ExecuteScriptCommand(script, DriverCommand.ExecuteScript, args);
         }
 
         /// <summary>
@@ -434,7 +434,7 @@ public object ExecuteScript(string script, params object[] args)
         /// <returns>The value returned by the script.</returns>
         public object ExecuteAsyncScript(string script, params object[] args)
         {
-            return this.ExecuteScriptInternal(script, true, args);
+            return this.ExecuteScriptCommand(script, DriverCommand.ExecuteAsyncScript, args);
         }
         #endregion
 
@@ -903,6 +903,33 @@ protected virtual RemoteWebElement CreateElement(string elementId)
             RemoteWebElement toReturn = new RemoteWebElement(this, elementId);
             return toReturn;
         }
+
+        protected object ExecuteScriptCommand(string script, string commandName, params object[] args)
+        {
+            if (!this.Capabilities.IsJavaScriptEnabled)
+            {
+                throw new NotSupportedException("You must be using an underlying instance of WebDriver that supports executing javascript");
+            }
+
+            // Escape the quote marks
+            // script = script.Replace("\"", "\\\"");
+            object[] convertedArgs = ConvertArgumentsToJavaScriptObjects(args);
+
+            Dictionary<string, object> parameters = new Dictionary<string, object>();
+            parameters.Add("script", script);
+
+            if (convertedArgs != null && convertedArgs.Length > 0)
+            {
+                parameters.Add("args", convertedArgs);
+            }
+            else
+            {
+                parameters.Add("args", new object[] { });
+            }
+
+            Response commandResponse = this.Execute(commandName, parameters);
+            return this.ParseJavaScriptReturnValue(commandResponse.Value);
+        }
         #endregion
 
         #region Private methods
@@ -962,6 +989,11 @@ private static object ConvertObjectToJavaScriptObject(object arg)
             return converted;
         }
 
+        /// <summary>
+        /// Converts the arguments to java script objects.
+        /// </summary>
+        /// <param name="args">The arguments.</param>
+        /// <returns></returns>
         private static object[] ConvertArgumentsToJavaScriptObjects(object[] args)
         {
             if (args == null)
@@ -1060,34 +1092,6 @@ private static void UnpackAndThrowOnError(Response errorResponse)
             }
         }
 
-        private object ExecuteScriptInternal(string script, bool async, params object[] args)
-        {
-            if (!this.Capabilities.IsJavaScriptEnabled)
-            {
-                throw new NotSupportedException("You must be using an underlying instance of WebDriver that supports executing javascript");
-            }
-
-            // Escape the quote marks
-            // script = script.Replace("\"", "\\\"");
-            object[] convertedArgs = ConvertArgumentsToJavaScriptObjects(args);
-
-            Dictionary<string, object> parameters = new Dictionary<string, object>();
-            parameters.Add("script", script);
-
-            if (convertedArgs != null && convertedArgs.Length > 0)
-            {
-                parameters.Add("args", convertedArgs);
-            }
-            else
-            {
-                parameters.Add("args", new object[] { });
-            }
-
-            string command = async ? DriverCommand.ExecuteAsyncScript : DriverCommand.ExecuteScript;
-            Response commandResponse = this.Execute(command, parameters);
-            return this.ParseJavaScriptReturnValue(commandResponse.Value);
-        }
-
         private object ParseJavaScriptReturnValue(object responseValue)
         {
             object returnValue = null;
diff --git a/dotnet/test/phantomjs/AssemblyTeardown.cs b/dotnet/test/phantomjs/AssemblyTeardown.cs
@@ -0,0 +1,23 @@
+﻿using NUnit.Framework;
+using OpenQA.Selenium.Environment;
+
+namespace OpenQA.Selenium.PhantomJS
+{
+    [SetUpFixture]
+    // Outside a namespace to affect the entire assembly
+    public class MySetUpClass
+    {
+        [SetUp]
+        public void RunBeforeAnyTest()
+        {
+            EnvironmentManager.Instance.WebServer.Start();
+        }
+
+        [TearDown]
+        public void RunAfterAnyTests()
+        {
+            EnvironmentManager.Instance.CloseCurrentDriver();
+            EnvironmentManager.Instance.WebServer.Stop();
+        }
+    }
+}
diff --git a/dotnet/test/phantomjs/PhantomJSSpecificTests.cs b/dotnet/test/phantomjs/PhantomJSSpecificTests.cs
@@ -0,0 +1,80 @@
+﻿using System;
+using System.Collections.Generic;
+using System.Linq;
+using System.Text;
+using NUnit.Framework;
+using OpenQA.Selenium.Environment;
+
+namespace OpenQA.Selenium.PhantomJS
+{
+    [TestFixture]
+    public class PhantomJSSpecificTests : DriverTestFixture
+    {
+        [Test]
+        public void ShouldBeAbleToReturnResultsFromScriptExecutedInPhantomJSContext()
+        {
+            if (!(driver is PhantomJSDriver))
+            {
+                // Skip this test if not using PhantomJS.
+                // The command under test is only available when using PhantomJS
+                return;
+            }
+
+            PhantomJSDriver phantom = (PhantomJSDriver)driver;
+
+            // Do we get results back?
+            object result = phantom.ExecutePhantomJS("return 1 + 1");
+            Assert.AreEqual(2L, (long)result);
+        }
+
+        [Test]
+        public void ShouldBeAbleToReadArgumentsInScriptExecutedInPhantomJSContext()
+        {
+            if (!(driver is PhantomJSDriver))
+            {
+                // Skip this test if not using PhantomJS.
+                // The command under test is only available when using PhantomJS
+                return;
+            }
+
+            PhantomJSDriver phantom = (PhantomJSDriver)driver;
+
+            // Can we read arguments?
+            object result = phantom.ExecutePhantomJS("return arguments[0] + arguments[0]", 1L);
+            Assert.AreEqual(2L, (long)result);
+        }
+
+        [Test]
+        public void ShouldBeAbleToOverrideScriptInPageFromPhantomJSContext()
+        {
+            if (!(driver is PhantomJSDriver))
+            {
+                // Skip this test if not using PhantomJS.
+                // The command under test is only available when using PhantomJS
+                return;
+            }
+
+            PhantomJSDriver phantom = (PhantomJSDriver)driver;
+
+            // Can we override some browser JavaScript functions in the page context?
+            object result = phantom.ExecutePhantomJS("var page = this;" +
+               "page.onInitialized = function () { " +
+                    "page.evaluate(function () { " +
+                        "Math.random = function() { return 42 / 100 } " +
+                    "})" +
+                "}");
+
+            phantom.Url = EnvironmentManager.Instance.UrlBuilder.WhereIs("injectableContent.html");
+            IWebElement numbers = phantom.FindElement(By.Id("numbers"));
+            bool foundAtLeastOne = false;
+            foreach (string number in numbers.Text.Split(' '))
+            {
+                foundAtLeastOne = true;
+                Assert.AreEqual("42", number);
+            }
+
+            Assert.IsTrue(foundAtLeastOne);
+        }
+    }
+}
+
diff --git a/dotnet/test/phantomjs/WebDriver.PhantomJS.Tests.csproj b/dotnet/test/phantomjs/WebDriver.PhantomJS.Tests.csproj
