Test.Sandwich.WebDriver

Introduce WebDriver servers and sessions.

Introducing a WebDriver server

introduceWebDriver

Arguments

:: forall context m. (BaseMonad m context, HasSomeCommandLineOptions context)

=> WebDriverDependencies

How to obtain dependencies

-> WdOptions

-> SpecFree (ContextWithWebdriverDeps context) m ()

-> SpecFree context m ()

Introduce a WebDriver, using the given WebDriverDependencies. A good default is defaultWebDriverDependencies.

introduceWebDriverViaNix

Arguments

:: forall m context. (BaseMonad m context, HasSomeCommandLineOptions context, HasNixContext context)

=> WdOptions

Options

-> SpecFree (ContextWithWebdriverDeps context) m ()

-> SpecFree context m ()

Introduce a WebDriver using the current NixContext. This will pull everything required from the configured Nixpkgs snapshot.

introduceWebDriverViaNix'

Arguments

:: forall m context. (BaseMonad m context, HasSomeCommandLineOptions context, HasNixContext context)

=> NodeOptions

-> WdOptions

Options

-> SpecFree (ContextWithWebdriverDeps context) m ()

-> SpecFree context m ()

Same as introduceWebDriverViaNix, but allows passing custom NodeOptions.

Non-Nix dependency fetching

When you aren't using Nix, these types specify how to obtain the necessary dependencies.

defaultWebDriverDependencies :: WebDriverDependencies

This configuration will

• Use java from the PATH, failing if it isn't found.
• Download Selenium to /tmp/tools, reusing the one there if found.
• Use firefox from the PATH as the browser.
• Download a compatible geckodriver to /tmp/tools, reusing the one there if found.
• If applicable, it will also get Xvfb, fluxbox, and/or ffmpeg from the PATH.

But, it's easy to customize this behavior. You can define your own WebDriverDependencies and customize how each of these dependencies are found.

data WebDriverDependencies

This type describes how we should obtain all the dependencies needed to launch a WebDriver session. You can configure them individually.

Constructors

WebDriverDependencies

Fields

• webDriverDependencyJava :: Maybe FilePath

  Path to java binary to use to start Selenium. If not provided, we'll search the PATH.

• webDriverDependencySelenium :: SeleniumToUse

  How to obtain a selenium.jar file.

• webDriverDependencyBrowser :: BrowserDependenciesSpec

  Browser/driver dependencies.

• webDriverXvfb :: XvfbDependenciesSpec

  How to obtain Xvfb (used for the RunInXvfb RunMode).

• webDriverFfmpeg :: FfmpegToUse

  How to obtain ffmpeg (used for video recording).

Running an example in a given session

Once you have a WebDriver in context, you can run one or more sessions. Each session will open an independent browser instance.

withSession

Arguments

:: forall m context a. (MonadMask m, MonadBaseControl IO m, HasBaseContext context, HasSomeCommandLineOptions context, WebDriverMonad m context)

=> Session

Session to run

-> ExampleT (LabelValue "webdriverSession" WebDriverSession :> context) m a

-> ExampleT context m a

Run a given example using a given Selenium session.

withSession1

Arguments

:: (MonadMask m, MonadBaseControl IO m, HasBaseContext context, HasSomeCommandLineOptions context, WebDriverMonad m context)

=> ExampleT (LabelValue "webdriverSession" WebDriverSession :> context) m a

Wrapped action

-> ExampleT context m a

Convenience function. withSession1 = withSession "session1".

withSession2

Arguments

:: (MonadMask m, MonadBaseControl IO m, HasBaseContext context, HasSomeCommandLineOptions context, WebDriverMonad m context)

=> ExampleT (LabelValue "webdriverSession" WebDriverSession :> context) m a

Wrapped action

-> ExampleT context m a

Convenience function. withSession2 = withSession "session2".

Managing sessions

getSessions :: (MonadReader context m, WebDriverMonad m context) => m [Session]

Get all existing session names.

closeCurrentSession :: (MonadLogger m, WebDriverSessionMonad m context) => m ()

Close the current session.

closeSession :: (HasCallStack, MonadLogger m, MonadUnliftIO m) => Session -> WebDriver -> m ()

Close the given session.

closeAllSessions :: (HasCallStack, MonadLogger m, MonadUnliftIO m) => WebDriver -> m ()

Close all sessions.

closeAllSessionsExcept :: (HasCallStack, MonadLogger m, MonadUnliftIO m) => [Session] -> WebDriver -> m ()

Close all sessions except those listed.

type Session = String

Session is just a String name.

Lower-level allocation functions

allocateWebDriver

Arguments

:: (BaseMonad m context, HasFile context "java", HasFile context "selenium.jar", HasBrowserDependencies context)

=> WdOptions

Options

-> OnDemandOptions

-> ExampleT context m WebDriver

Allocate a WebDriver using the given options.

cleanupWebDriver :: BaseMonad m context => WebDriver -> ExampleT context m ()

Clean up the given WebDriver.

introduceBrowserDependenciesViaNix

Arguments

:: forall m context. (MonadUnliftIO m, HasBaseContext context, HasNixContext context, HasSomeCommandLineOptions context)

=> SpecFree (LabelValue "browserDependencies" BrowserDependencies :> context) m ()

Child spec

-> SpecFree context m ()

Parent spec

Introduce BrowserDependencies via Nix, using the command line options. This is useful to create the context for functions like allocateWebDriver.

introduceBrowserDependenciesViaNix'

Arguments

:: forall m context. (MonadUnliftIO m, HasBaseContext context, HasNixContext context, HasSomeCommandLineOptions context)

=> NodeOptions

-> SpecFree (LabelValue "browserDependencies" BrowserDependencies :> context) m ()

Child spec

-> SpecFree context m ()

Parent spec

Same as introduceBrowserDependenciesViaNix, but allows passing custom NodeOptions.

introduceWebDriver'

Arguments

:: forall m context. BaseMonad m context

=> WebDriverDependencies

Dependencies

-> (WdOptions -> ExampleT (ContextWithBaseDeps context) m WebDriver)

-> WdOptions

-> SpecFree (ContextWithWebdriverDeps context) m ()

-> SpecFree context m ()

Same as introduceWebDriver, but with a controllable allocation callback.

addCommandLineOptionsToWdOptions :: SomeCommandLineOptions -> WdOptions -> WdOptions

Merge the options from the CommandLineOptions into some WdOptions.

Context types

WebDriver

webdriver :: Label "webdriver" WebDriver

data WebDriver

type HasWebDriverContext context = HasLabel context "webdriver" WebDriver

WebDriverSession

webdriverSession :: Label "webdriverSession" WebDriverSession

type WebDriverSession = (Session, IORef WDSession)

type HasWebDriverSessionContext context = HasLabel context "webdriverSession" WebDriverSession

Shorthands

These are used to make type signatures shorter.

type BaseMonad m context = (HasCallStack, MonadUnliftIO m, MonadMask m, HasBaseContext context)

type ContextWithBaseDeps context

Arguments

 = LabelValue "browserDependencies" BrowserDependencies :> (FileValue "java" :> (FileValue "selenium.jar" :> context))

Browser dependencies

type ContextWithWebdriverDeps context = LabelValue "webdriver" WebDriver :> ContextWithBaseDeps context

type WebDriverMonad m context = (HasCallStack, MonadUnliftIO m, HasWebDriverContext context)

type WebDriverSessionMonad m context = (WebDriverMonad m context, MonadReader context m, HasWebDriverSessionContext context)

On demand options

data OnDemandOptions

How to obtain certain binaries "on demand". These may or not be needed based on WdOptions, so they will be obtained as needed.

defaultOnDemandOptions :: OnDemandOptions

Re-exports

module Test.Sandwich.WebDriver.Config