Trait that provides a new Selenium WebDriver instance per ScalaTest Suite.

This TestSuiteMixin trait's overridden run method places a reference to the WebDriver provided by webDriver under the key org.scalatestplus.play.webDriver. This allows any nested Suites to access the Suite's WebDriver as well, most easily by having the nested Suites mix in the ConfiguredBrowser trait. On the status returned by super.run, this trait's overridden run method registers a block of code to close the WebDriver to be executed when the Status completes, and returns the same Status. This ensures the WebDriver will continue to be available until all nested suites have completed, after which the WebDriver will be closed. This trait also overrides Suite.withFixture to cancel tests automatically if the related WebDriver is not available on the host platform.

This trait's self-type, ServerProvider, will ensure a TestServer and Application are available to each test. The self-type will require that you mix in either GuiceOneServerPerSuite, OneServerPerTest, ConfiguredServer before you mix in this trait. Your choice among these three ServerProviders will determine the extent to which one or more TestServers are shared by multiple tests.

Here's an example that shows demonstrates of the services provided by this trait. Note that to use this trait, you must mix in one of the driver factories (this example mixes in FirefoxFactory):

package org.scalatestplus.play.examples.onebrowserpersuite

import play.api.test.Helpers
import org.scalatest.tags.FirefoxBrowser
import org.scalatestplus.play._
import play.api.{Play, Application}
import play.api.inject.guice._
import play.api.routing._

@FirefoxBrowser
class ExampleSpec extends PlaySpec with OneServerPerSuite with OneBrowserPerSuite with FirefoxFactory {

  // Override fakeApplication() if you need a Application with other than non-default parameters.
  def fakeApplication(): Application = new GuiceApplicationBuilder()
    .configure("foo" -> "bar", "ehcacheplugin" -> "disabled")
    .router(TestRoutes.router)
    .build()

  "The OneBrowserPerSuite trait" must {
    "provide an Application" in {
      app.configuration.getOptional[String]("ehcacheplugin") mustBe Some("disabled")
    }
    "make the Application available implicitly" in {
      def getConfig(key: String)(implicit app: Application) = app.configuration.getOptional[String](key)
      getConfig("ehcacheplugin") mustBe Some("disabled")
    }
    "start the Application" in {
      Play.maybeApplication mustBe Some(app)
    }
    "provide the port number" in {
      port mustBe Helpers.testServerPort
    }
    "provide an actual running server" in {
      import java.net._
      val url = new URL("http://localhost:" + port + "/boum")
      val con = url.openConnection().asInstanceOf[HttpURLConnection]
      try con.getResponseCode mustBe 404
      finally con.disconnect()
    }
    "provide a web driver" in {
      go to ("http://localhost:" + port + "/testing")
      pageTitle mustBe "Test Page"
      click on find(name("b")).value
      eventually { pageTitle mustBe "scalatest" }
    }
  }
}

If you have many tests that can share the same Application, TestServer, and WebDriver, and you don't want to put them all into one test class, you can place them into different "nested" Suite classes. Create a master suite that extends OneServerPerSuite and declares the nested Suites. Annotate the nested suites with @DoNotDiscover and have them extend ConfiguredBrowser. Here's an example:

package org.scalatestplus.play.examples.onebrowserpersuite

import play.api.test._
import org.scalatest._
import tags.FirefoxBrowser
import org.scalatestplus.play._
import play.api.{Play, Application}

// This is the "master" suite
class NestedExampleSpec extends Suites(
  new OneSpec,
  new TwoSpec,
  new RedSpec,
  new BlueSpec
) with OneServerPerSuite with OneBrowserPerSuite with FirefoxFactory {
  // Override fakeApplication() if you need a Application with other than non-default parameters.
  def fakeApplication(): Application =
    new GuiceApplicationBuilder(
      additionalConfiguration = Map("ehcacheplugin" -> "disabled"),
      withRoutes = TestRoute
    ).build()
}

// These are the nested suites
@DoNotDiscover class OneSpec extends PlaySpec with ConfiguredServer with ConfiguredBrowser
@DoNotDiscover class TwoSpec extends PlaySpec with ConfiguredServer with ConfiguredBrowser
@DoNotDiscover class RedSpec extends PlaySpec with ConfiguredServer with ConfiguredBrowser

@DoNotDiscover
class BlueSpec extends PlaySpec with ConfiguredServer with ConfiguredBrowser {

  "The OneBrowserPerSuite trait" must {
    "provide an Application" in {
      app.configuration.getOptional[String]("ehcacheplugin") mustBe Some("disabled")
    }
    "make the Application available implicitly" in {
      def getConfig(key: String)(implicit app: Application) = app.configuration.getOptional[String](key)
      getConfig("ehcacheplugin") mustBe Some("disabled")
    }
    "start the Application" in {
      Play.maybeApplication mustBe Some(app)
    }
    "provide the port number" in {
      port mustBe Helpers.testServerPort
    }
    "provide an actual running server" in {
      import Helpers._
      import java.net._
      val url = new URL("http://localhost:" + port + "/boum")
      val con = url.openConnection().asInstanceOf[HttpURLConnection]
      try con.getResponseCode mustBe 404
      finally con.disconnect()
    }
  }
}

It is possible to use OneBrowserPerSuite to run the same tests in more than one browser. Nevertheless, you should consider the approach taken by AllBrowsersPerSuite and AllBrowsersPerTest instead, as it requires a bit less boilerplate code than OneBrowserPerSuite to test in multiple browsers. If you prefer to use OneBrowserPerSuite, however, simply place your tests in an abstract superclass, then define concrete subclasses for each browser you wish to test against. Here's an example:

package org.scalatestplus.play.examples.onebrowserpersuite

import play.api.test._
import org.scalatest._
import tags._
import org.scalatestplus.play._
import play.api.{Play, Application}

// Place your tests in an abstract class
abstract class MultiBrowserExampleSpec extends PlaySpec with OneServerPerSuite with OneBrowserPerSuite {

  // Override app if you need an Application with other than non-default parameters.
  def fakeApplication(): Application =
    new GuiceApplicationBuilder(
      additionalConfiguration = Map("ehcacheplugin" -> "disabled"),
      withRoutes = TestRoute
    ).build

  "The OneBrowserPerSuite trait" must {
    "provide an Application" in {
      app.configuration.getOptional[String]("ehcacheplugin") mustBe Some("disabled")
    }
    "make the Application available implicitly" in {
      def getConfig(key: String)(implicit app: Application) = app.configuration.getOptional[String](key)
      getConfig("ehcacheplugin") mustBe Some("disabled")
    }
    "start the Application" in {
      Play.maybeApplication mustBe Some(app)
    }
    "provide the port number" in {
      port mustBe Helpers.testServerPort
    }
    "provide an actual running server" in {
      import Helpers._
      import java.net._
      val url = new URL("http://localhost:" + port + "/boum")
      val con = url.openConnection().asInstanceOf[HttpURLConnection]
      try con.getResponseCode mustBe 404
      finally con.disconnect()
    }
    "provide a web driver" in {
      go to ("http://localhost:" + port + "/testing")
      pageTitle mustBe "Test Page"
      click on find(name("b")).value
      eventually { pageTitle mustBe "scalatest" }
    }
  }
}

// Then make a subclass that mixes in the factory for each
// Selenium driver you want to test with.
@FirefoxBrowser class FirefoxExampleSpec extends MultiBrowserExampleSpec with FirefoxFactory
@SafariBrowser class SafariExampleSpec extends MultiBrowserExampleSpec with SafariFactory
@InternetExplorerBrowser class InternetExplorerExampleSpec extends MultiBrowserExampleSpec with InternetExplorerFactory
@ChromeBrowser class ChromeExampleSpec extends MultiBrowserExampleSpec with ChromeFactory
@HtmlUnitBrowser class HtmlUnitExampleSpec extends MultiBrowserExampleSpec with HtmlUnitFactory

The concrete subclasses include tag annotations describing the browser used to make it easier to include or exclude browsers in specific runs. This is not strictly necessary since if a browser is not supported on the host platform the tests will be automatically canceled. For example, here's how the output would look if you ran the above tests on a platform that did not support Selenium drivers for Chrome or Internet Explorer using sbt:

> test-only *onebrowserpersuite*
[info] FirefoxExampleSpec:
[info] The OneBrowserPerSuite trait
[info] - must provide an Application
[info] - must make the Application available implicitly
[info] - must start the Application
[info] - must provide the port number
[info] - must provide an actual running server
[info] - must provide a web driver
[info] SafariExampleSpec:
[info] The OneBrowserPerSuite trait
[info] - must provide an Application
[info] - must make the Application available implicitly
[info] - must start the Application
[info] - must provide the port number
[info] - must provide an actual running server
[info] - must provide a web driver
[info] InternetExplorerExampleSpec:
[info] The OneBrowserPerSuite trait
[info] - must provide an Application !!! CANCELED !!!
[info]   Was unable to create a Selenium InternetExplorerDriver on this platform. (OneBrowserPerSuite.scala:201)
[info] - must make the Application available implicitly !!! CANCELED !!!
[info]   Was unable to create a Selenium InternetExplorerDriver on this platform. (OneBrowserPerSuite.scala:201)
[info] - must start the Application !!! CANCELED !!!
[info]   Was unable to create a Selenium InternetExplorerDriver on this platform. (OneBrowserPerSuite.scala:201)
[info] - must provide the port number !!! CANCELED !!!
[info]   Was unable to create a Selenium InternetExplorerDriver on this platform. (OneBrowserPerSuite.scala:201)
[info] - must provide an actual running server !!! CANCELED !!!
[info]   Was unable to create a Selenium InternetExplorerDriver on this platform. (OneBrowserPerSuite.scala:201)
[info] - must provide a web driver !!! CANCELED !!!
[info]   Was unable to create a Selenium InternetExplorerDriver on this platform. (OneBrowserPerSuite.scala:201)
[info] ChromeExampleSpec:
[info] The OneBrowserPerSuite trait
[info] - must provide an Application !!! CANCELED !!!
[info]   Was unable to create a Selenium ChromeDriver on this platform. (OneBrowserPerSuite.scala:201)
[info] - must make the Application available implicitly !!! CANCELED !!!
[info]   Was unable to create a Selenium ChromeDriver on this platform. (OneBrowserPerSuite.scala:201)
[info] - must start the Application !!! CANCELED !!!
[info]   Was unable to create a Selenium ChromeDriver on this platform. (OneBrowserPerSuite.scala:201)
[info] - must provide the port number !!! CANCELED !!!
[info]   Was unable to create a Selenium ChromeDriver on this platform. (OneBrowserPerSuite.scala:201)
[info] - must provide an actual running server !!! CANCELED !!!
[info]   Was unable to create a Selenium ChromeDriver on this platform. (OneBrowserPerSuite.scala:201)
[info] - must provide a web driver !!! CANCELED !!!
[info]   Was unable to create a Selenium ChromeDriver on this platform. (OneBrowserPerSuite.scala:201)
[info] HtmlUnitExampleSpec:
[info] The OneBrowserPerSuite trait
[info] - must provide an Application
[info] - must make the Application available implicitly
[info] - must start the Application
[info] - must provide the port number
[info] - must provide an actual running server
[info] - must provide a web driver

For comparison, here is what the output would look like if you just selected tests tagged with FirefoxBrowser in sbt:

> test-only *onebrowserpersuite* -- -n org.scalatest.tags.FirefoxBrowser
[info] FirefoxExampleSpec:
[info] The OneBrowserPerSuite trait
[info] - must provide an Application
[info] - must make the Application available implicitly
[info] - must start the Application
[info] - must provide the port number
[info] - must provide an actual running server
[info] - must provide a web driver
[info] SafariExampleSpec:
[info] The OneBrowserPerSuite trait
[info] InternetExplorerExampleSpec:
[info] The OneBrowserPerSuite trait
[info] ChromeExampleSpec:
[info] The OneBrowserPerSuite trait
[info] HtmlUnitExampleSpec:
[info] The OneBrowserPerSuite trait