Deprecate PhantomJS (#476)

* Deprecate Wallaby.Phantom

- Warns on use of `Wallaby.Phantom`
- Documents `Wallaby.Phantom` as deprecated
- Makes `Wallaby.Chrome` the default driver
- Removes references to phantomjs in the README

CHANGELOG.md

@@ -2,6 +2,16 @@
 
 ## Master
 
+### Deprecations
+
+- Deprecated `Wallaby.Phantom`, please switch to `Wallaby.Chrome` or `Wallaby.Selenium`
+
+### Breaking
+
+- `Wallaby.Experimental.Chrome` renamed to `Wallaby.Chrome`.
+- `Wallaby.Experimental.Selenium` renamed to `Wallaby.Selenium`.
+- `Wallaby.Chrome` is now the default driver.
+
 ## 0.24.1 (2020-05-21)
 
 - Compatibility fix for ChromeDriver version >= 83. Fixes [#533](https://github.com/elixir-wallaby/wallaby/issues/533)

README.md

@@ -83,6 +83,16 @@ def deps do
 end
 ```
 
+Configure the driver.
+
+```elixir
+# Chrome
+config :wallaby, driver: Wallaby.Chrome # default
+
+# Selenium
+config :wallaby, driver: Wallaby.Selenium
+```
+
 Then ensure that Wallaby is started in your `test_helper.exs`:
 
 ```elixir
@@ -212,26 +222,6 @@ def deps do
 end
 ```
 
-### PhantomJS
-
-Wallaby requires PhantomJS. You can install PhantomJS through NPM or your package manager of choice:
-
-```
-$ npm install -g phantomjs-prebuilt
-```
-
-Wallaby will use whatever PhantomJS you have installed in your path. If you need to specify a specific PhantomJS you can pass the path in the configuration:
-
-```elixir
-config :wallaby, phantomjs: "some/path/to/phantomjs"
-```
-
-You can also pass arguments to PhantomJS through the `phantomjs_args` config setting, e.g.:
-
-```elixir
-config :wallaby, phantomjs_args: "--webdriver-logfile=phantomjs.log"
-```
-
 ### Writing tests
 
 It's easiest to add Wallaby to your test suite by using the `Wallaby.Feature` module.
@@ -494,7 +484,7 @@ Application.put_env(:wallaby, :js_logger, file)
 
 Logging can be disabled by setting `:js_logger` to `nil`.
 
-## Config
+## Configuration
 
 ### Adjusting timeouts
 
@@ -510,64 +500,34 @@ config :wallaby,
   hackney_options: [timeout: 5_000]
 ```
 
-### Drivers
-
-Wallaby works with PhantomJS out of the box. There is also experimental support for both headless chrome and selenium.
-The driver can be specified by setting the `driver` option in the wallaby config like so:
-
-```elixir
-# Chrome
-config :wallaby,
-  driver: Wallaby.Experimental.Chrome
-
-# Selenium
-config :wallaby,
-  driver: Wallaby.Experimental.Selenium
-```
-
-See below for more information on the experimental drivers.
-
-## Experimental Driver Support
-
-Currently Wallaby provides experimental support for both headless chrome and selenium.
-Both of these drivers are still "experimental" because they don't support the full API yet and because the implementation is changing rapidly.
-But, if you would like to use them in your project here's what you'll need to do.
-
-### Chromedriver
+## Contributing
 
-Please refer to the [documentation](https://hexdocs.pm/wallaby/Wallaby.Experimental.Chrome.html#content) for further information about using Chromedriver.
+Wallaby is a community project. PRs and Issues are greatly welcome.
 
-#### Headless Chrome
+To get started and setup the project, make sure you've got Elixir 1.7+ installed and then:
 
-In order to run headless chrome you'll need to have ChromeDriver >= 2.30 and chrome >= 60.
-Previous versions of both of these tools _may_ work, but several features will be buggy.
-If you want to setup chrome in a CI environment then you'll still need to install and run xvfb.
-This is due to a bug in ChromeDriver 2.30 that inhibits ChromeDriver from handling input text correctly.
-The bug should be fixed in ChromeDriver 2.31.
+### Development Dependencies
 
-### Selenium
+Wallaby requires the following tools.
 
-Please refer to the [documentation](https://hexdocs.pm/wallaby/Wallaby.Experimental.Selenium.html#content) for further information about using Selenium.
+- ChromeDriver
+- Google Chrome
+- GeckoDriver
+- Mozilla Firefox
+- selenium-server-standalone
 
-## Contributing
 
-Wallaby is a community project. PRs and Issues are greatly welcome.
+```shell
+# Unit tests
+$ mix test
 
-To get started and setup the project, make sure you've got Elixir 1.7+ installed and then:
+# Integration tests for all drivers
+$ mix test.drivers
 
-```
-$ mix deps.get
-$ npm install -g phantomjs-prebuilt # unless you've already got PhantomJS installed
-$ mix test # Make sure the tests pass!
-```
-
-Besides running the unit tests above, it is recommended to run the driver
-integration tests too:
-
-```
-# Run only phantomjs integration tests
-$ WALLABY_DRIVER=phantom mix test
+# Integration tests for a specific driver
+$ WALLABY_DRIVER=chrome mix test
+$ WALLABY_DRIVER=selenium mix test
 
-# Run all tests (unit and all drivers)
+# All tests
 $ mix test.all
 ```

integration_test/chrome/capabilities_test.exs

@@ -5,7 +5,7 @@ defmodule Wallaby.Integration.CapabilitiesTest do
   import Wallaby.SettingsTestHelpers
 
   alias Wallaby.Integration.SessionCase
-  alias Wallaby.Experimental.Selenium.WebdriverClient
+  alias Wallaby.WebdriverClient
 
   setup do
     ensure_setting_is_reset(:wallaby, :chromedriver)

integration_test/chrome/starting_sessions_test.exs

@@ -6,7 +6,7 @@ defmodule Wallaby.Integration.Chrome.StartingSessionsTest do
   import Wallaby.TestSupport.TestScriptUtils
   import Wallaby.TestSupport.TestWorkspace
 
-  alias Wallaby.Experimental.Chrome
+  alias Wallaby.Chrome
   alias Wallaby.TestSupport.Chrome.ChromeTestScript
   alias Wallaby.TestSupport.TestWorkspace
 

lib/wallaby.ex

@@ -19,6 +19,13 @@ defmodule Wallaby do
   * `:phantomjs` - The path to the phantomjs executable (defaults to "phantomjs")
   * `:phantomjs_args` - Any extra arguments that should be passed to phantomjs (defaults to "")
   """
+
+  @drivers %{
+    "chrome" => Wallaby.Chrome,
+    "selenium" => Wallaby.Selenium,
+    "phantom" => Wallaby.Phantom
+  }
+
   use Application
 
   alias Wallaby.Session
@@ -111,18 +118,19 @@ defmodule Wallaby do
   end
 
   def driver do
-    case System.get_env("WALLABY_DRIVER") do
-      "chrome" ->
-        Wallaby.Experimental.Chrome
-
-      "selenium" ->
-        Wallaby.Experimental.Selenium
-
-      "phantom" ->
-        Wallaby.Phantom
-
-      _ ->
-        Application.get_env(:wallaby, :driver, Wallaby.Phantom)
+    driver =
+      Map.get(
+        @drivers,
+        System.get_env("WALLABY_DRIVER"),
+        Application.get_env(:wallaby, :driver, Wallaby.Chrome)
+      )
+
+    if driver == Wallaby.Phantom do
+      IO.warn(
+        "Wallaby.Phantom is deprecated, please use Wallaby.Chrome or Wallaby.Selenium instead."
+      )
     end
+
+    driver
   end
 end

lib/wallaby/experimental/chrome.ex → lib/wallaby/chrome.ex

@@ -1,4 +1,4 @@
-defmodule Wallaby.Experimental.Chrome do
+defmodule Wallaby.Chrome do
   @moduledoc """
   The Chrome driver uses [Chromedriver](https://sites.google.com/a/chromium.org/chromedriver/) to power Google Chrome and Chromium.
 
@@ -110,8 +110,8 @@ defmodule Wallaby.Experimental.Chrome do
   @chromedriver_version_regex ~r/^ChromeDriver (\d+)\.(\d+)/
 
   alias Wallaby.{DependencyError, Metadata}
-  alias Wallaby.Experimental.Chrome.{Chromedriver}
-  alias Wallaby.Experimental.Selenium.WebdriverClient
+  alias Wallaby.Chrome.{Chromedriver}
+  alias Wallaby.WebdriverClient
   import Wallaby.Driver.LogChecker
 
   @typedoc """
@@ -145,7 +145,7 @@ defmodule Wallaby.Experimental.Chrome do
   def init(:ok) do
     children = [
       Wallaby.Driver.LogStore,
-      Wallaby.Experimental.Chrome.Chromedriver
+      Wallaby.Chrome.Chromedriver
     ]
 
     Supervisor.init(children, strategy: :one_for_one)
@@ -292,7 +292,7 @@ defmodule Wallaby.Experimental.Chrome do
   @doc false
   defdelegate dismiss_prompt(session, fun), to: WebdriverClient
   @doc false
-  defdelegate parse_log(log), to: Wallaby.Experimental.Chrome.Logger
+  defdelegate parse_log(log), to: Wallaby.Chrome.Logger
 
   @doc false
   def window_handle(session), do: delegate(:window_handle, session)

lib/wallaby/experimental/chrome/chromedriver.ex → lib/wallaby/chrome/chromedriver.ex

@@ -1,8 +1,8 @@
-defmodule Wallaby.Experimental.Chrome.Chromedriver do
+defmodule Wallaby.Chrome.Chromedriver do
   @moduledoc false
 
-  alias Wallaby.Experimental.Chrome
-  alias Wallaby.Experimental.Chrome.Chromedriver.Server
+  alias Wallaby.Chrome
+  alias Wallaby.Chrome.Chromedriver.Server
 
   @instance __MODULE__
 

lib/wallaby/experimental/chrome/chromedriver/readiness_checker.ex → lib/wallaby/chrome/chromedriver/readiness_checker.ex

@@ -1,4 +1,4 @@
-defmodule Wallaby.Experimental.Chrome.Chromedriver.ReadinessChecker do
+defmodule Wallaby.Chrome.Chromedriver.ReadinessChecker do
   @moduledoc false
 
   alias WebDriverClient.Config

lib/wallaby/experimental/chrome/chromedriver/server.ex → lib/wallaby/chrome/chromedriver/server.ex

@@ -1,9 +1,9 @@
-defmodule Wallaby.Experimental.Chrome.Chromedriver.Server do
+defmodule Wallaby.Chrome.Chromedriver.Server do
   @moduledoc false
   use GenServer
 
   alias Wallaby.Driver.Utils
-  alias Wallaby.Experimental.Chrome.Chromedriver.ReadinessChecker
+  alias Wallaby.Chrome.Chromedriver.ReadinessChecker
 
   defmodule State do
     @moduledoc false

lib/wallaby/experimental/chrome/logger.ex → lib/wallaby/chrome/logger.ex

@@ -1,4 +1,4 @@
-defmodule Wallaby.Experimental.Chrome.Logger do
+defmodule Wallaby.Chrome.Logger do
   @moduledoc false
   @log_regex ~r/^(?<url>\S+) (?<line>\d+):(?<column>\d+) (?<message>.*)$/s
   @string_regex ~r/^"(?<string>.+)"$/

lib/wallaby/phantom.ex

@@ -30,6 +30,7 @@ defmodule Wallaby.Phantom do
   config :wallaby, phantomjs_args: "--webdriver-logfile=phantomjs.log"
   ```
   """
+  @moduledoc deprecated: "Please use Wallaby.Chrome or Wallaby.Selenium instead."
 
   use Supervisor
 

lib/wallaby/experimental/selenium.ex → lib/wallaby/selenium.ex

@@ -1,4 +1,4 @@
-defmodule Wallaby.Experimental.Selenium do
+defmodule Wallaby.Selenium do
   @moduledoc """
   The Selenium driver uses [Selenium Server](https://github.com/SeleniumHQ/selenium) to power many types of browsers (Chrome, Firefox, Edge, etc).
 
@@ -52,7 +52,7 @@ defmodule Wallaby.Experimental.Selenium do
   @behaviour Wallaby.Driver
 
   alias Wallaby.{Driver, Element, Session}
-  alias Wallaby.Experimental.Selenium.WebdriverClient
+  alias Wallaby.WebdriverClient
 
   @typedoc """
   Options to pass to Wallaby.start_session/1

lib/wallaby/session_store.ex

@@ -2,7 +2,7 @@ defmodule Wallaby.SessionStore do
   @moduledoc false
   use GenServer
 
-  alias Wallaby.Experimental.Selenium.WebdriverClient
+  alias Wallaby.WebdriverClient
 
   def start_link, do: GenServer.start_link(__MODULE__, :ok, name: __MODULE__)
 

lib/wallaby/experimental/selenium/webdriver_client.ex → lib/wallaby/webdriver_client.ex

@@ -1,4 +1,4 @@
-defmodule Wallaby.Experimental.Selenium.WebdriverClient do
+defmodule Wallaby.WebdriverClient do
   @moduledoc false
   # Client implementation for the WebDriver Wire Protocol
   # documented on https://github.com/SeleniumHQ/selenium/wiki/JsonWireProtocol

test/wallaby/experimental/chrome/chromedriver/server_test.exs → test/wallaby/chrome/chromedriver/server_test.exs

@@ -1,12 +1,12 @@
-defmodule Wallaby.Experimental.Chrome.Chromedriver.ServerTest do
+defmodule Wallaby.Chrome.Chromedriver.ServerTest do
   use ExUnit.Case, async: true
 
   alias Wallaby.TestSupport.Chrome.ChromeTestScript
   alias Wallaby.TestSupport.TestScriptUtils
   alias Wallaby.TestSupport.TestWorkspace
 
-  alias Wallaby.Experimental.Chrome
-  alias Wallaby.Experimental.Chrome.Chromedriver.Server
+  alias Wallaby.Chrome
+  alias Wallaby.Chrome.Chromedriver.Server
 
   @moduletag :capture_log
 

test/wallaby/experimental/chrome/logger_test.exs → test/wallaby/chrome/logger_test.exs

@@ -1,7 +1,7 @@
-defmodule Wallaby.Experimental.Chrome.LoggerTest do
+defmodule Wallaby.Chrome.LoggerTest do
   use ExUnit.Case, async: false
 
-  alias Wallaby.Experimental.Chrome.Logger
+  alias Wallaby.Chrome.Logger
   import ExUnit.CaptureIO
   alias Wallaby.SettingsTestHelpers
 

test/wallaby/experimental/selenium/start_session_config_test.exs → test/wallaby/selenium/start_session_config_test.exs

@@ -1,10 +1,10 @@
-defmodule Wallaby.Experimental.Selenium.StartSessionConfigTest do
+defmodule Wallaby.Selenium.StartSessionConfigTest do
   use Wallaby.HttpClientCase, async: false
 
   # These tests modify the application environment so need
   # to be run with async: false
 
-  alias Wallaby.Experimental.Selenium
+  alias Wallaby.Selenium
   alias Wallaby.Session
   alias Wallaby.SettingsTestHelpers
   alias Wallaby.TestSupport.JSONWireProtocolResponses