sandwich-webdriver: more on haddocks and demos

demos/demo-discover/app/Types.hs

@@ -5,7 +5,6 @@ module Types where
 
 import Test.Sandwich
 import Test.Sandwich.WebDriver
-import Test.Sandwich.WebDriver.Types
 
 
 type SeleniumSpec = forall context. (

demos/demo-webdriver/demo-webdriver.cabal → demos/demo-webdriver-nix/demo-webdriver-nix.cabal

@@ -1,19 +1,19 @@
 cabal-version: 1.12
 
--- This file has been generated from package.yaml by hpack version 0.36.0.
+-- This file has been generated from package.yaml by hpack version 0.37.0.
 --
 -- see: https://github.com/sol/hpack
 
-name:           demo-webdriver
+name:           demo-webdriver-nix
 version:        0.1.0.0
 license:        BSD3
 license-file:   LICENSE
 build-type:     Simple
 
-executable demo-webdriver
+executable demo-webdriver-nix
   main-is: Main.hs
   other-modules:
-      Paths_demo_webdriver
+      Paths_demo_webdriver_nix
   hs-source-dirs:
       app
   default-extensions:

demos/demo-webdriver/package.yaml → demos/demo-webdriver-nix/package.yaml

@@ -1,4 +1,4 @@
-name:                demo-webdriver
+name:                demo-webdriver-nix
 version:             0.1.0.0
 license:             BSD3
 
@@ -28,6 +28,6 @@ ghc-options:
 - -with-rtsopts=-N
 
 executables:
-  demo-webdriver:
+  demo-webdriver-nix:
     main: Main.hs
     source-dirs: app

demos/demo-webdriver-normal/LICENSE

@@ -0,0 +1,30 @@
+Copyright Tom McLaughlin (c) 2024
+
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+    * Redistributions of source code must retain the above copyright
+      notice, this list of conditions and the following disclaimer.
+
+    * Redistributions in binary form must reproduce the above
+      copyright notice, this list of conditions and the following
+      disclaimer in the documentation and/or other materials provided
+      with the distribution.
+
+    * Neither the name of Tom McLaughlin nor the names of other
+      contributors may be used to endorse or promote products derived
+      from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

demos/demo-webdriver-normal/app/Main.hs

@@ -0,0 +1,41 @@
+{-# LANGUAGE AllowAmbiguousTypes #-}
+{-# LANGUAGE DataKinds #-}
+{-# LANGUAGE NumericUnderscores #-}
+{-# LANGUAGE OverloadedStrings #-}
+{-# LANGUAGE QuasiQuotes #-}
+{-# LANGUAGE TypeApplications #-}
+{-# LANGUAGE TypeOperators #-}
+
+module Main where
+
+import Control.Concurrent
+import Control.Monad.IO.Class
+import qualified Data.ByteString.Lazy as BL
+import Data.String.Interpolate
+import System.FilePath
+import Test.Sandwich
+import Test.Sandwich.Contexts.Nix
+import Test.Sandwich.WebDriver
+import Test.WebDriver.Commands
+
+
+simple :: TopSpecWithOptions
+simple = introduceWebDriver defaultWebDriverDependencies defaultWdOptions $ do
+  it "opens Google and searches" $ withSession1 $ do
+    openPage [i|https://www.google.com|]
+    search <- findElem (ByCSS [i|*[title="Search"]|])
+    click search
+    sendKeys "Haskell Sandwich" search
+    findElem (ByCSS [i|input[type="submit"]|]) >>= click
+
+    Just dir <- getCurrentFolder
+    screenshot >>= liftIO . BL.writeFile (dir </> "screenshot.png")
+
+    liftIO $ threadDelay 3_000_000
+
+testOptions = defaultOptions {
+  optionsTestArtifactsDirectory = defaultTestArtifactsDirectory
+  }
+
+main :: IO ()
+main = runSandwichWithCommandLineArgs testOptions simple

demos/demo-webdriver-normal/demo-webdriver-normal.cabal

@@ -0,0 +1,38 @@
+cabal-version: 1.12
+
+-- This file has been generated from package.yaml by hpack version 0.37.0.
+--
+-- see: https://github.com/sol/hpack
+
+name:           demo-webdriver-normal
+version:        0.1.0.0
+license:        BSD3
+license-file:   LICENSE
+build-type:     Simple
+
+executable demo-webdriver-normal
+  main-is: Main.hs
+  other-modules:
+      Paths_demo_webdriver_normal
+  hs-source-dirs:
+      app
+  default-extensions:
+      OverloadedStrings
+      QuasiQuotes
+      NamedFieldPuns
+      RecordWildCards
+      ScopedTypeVariables
+      FlexibleContexts
+      FlexibleInstances
+      LambdaCase
+  ghc-options: -threaded -rtsopts -with-rtsopts=-N
+  build-depends:
+      base
+    , bytestring
+    , filepath
+    , sandwich
+    , sandwich-contexts
+    , sandwich-webdriver
+    , string-interpolate
+    , webdriver
+  default-language: Haskell2010

demos/demo-webdriver-normal/package.yaml

@@ -0,0 +1,33 @@
+name:                demo-webdriver-normal
+version:             0.1.0.0
+license:             BSD3
+
+dependencies:
+- base
+- bytestring
+- filepath
+- sandwich
+- sandwich-contexts
+- sandwich-webdriver
+- string-interpolate
+- webdriver
+
+default-extensions:
+- OverloadedStrings
+- QuasiQuotes
+- NamedFieldPuns
+- RecordWildCards
+- ScopedTypeVariables
+- FlexibleContexts
+- FlexibleInstances
+- LambdaCase
+
+ghc-options:
+- -threaded
+- -rtsopts
+- -with-rtsopts=-N
+
+executables:
+  demo-webdriver-normal:
+    main: Main.hs
+    source-dirs: app

demos/demo-webdriver-pool/app/Main.hs

@@ -24,7 +24,6 @@ import Test.Sandwich
 import Test.Sandwich.Contexts.Files
 import Test.Sandwich.Contexts.Nix
 import Test.Sandwich.WebDriver
-import Test.Sandwich.WebDriver.Types
 import Test.Sandwich.WebDriver.Video
 import Test.Sandwich.WebDriver.Windows
 import Test.WebDriver.Commands

sandwich-webdriver/src/Test/Sandwich/WebDriver.hs

@@ -50,6 +50,7 @@ module Test.Sandwich.WebDriver (
   , HasWebDriverSessionContext
   -- * Shorthands
   , BaseMonad
+  , ContextWithBaseDeps
   , ContextWithWebdriverDeps
   , WebDriverMonad
 

sandwich-webdriver/src/Test/Sandwich/WebDriver/Config.hs

@@ -1,4 +1,6 @@
 
+-- | Configuration types for WebDriver servers, Xvfb mode, browser capabilities, etc.
+
 module Test.Sandwich.WebDriver.Config (
   -- * Main options
   WdOptions

sandwich-webdriver/src/Test/Sandwich/WebDriver/Internal/Types.hs

@@ -83,7 +83,7 @@ defaultOnDemandOptions = OnDemandOptions {
 -- | Configuration for a headless browser.
 data HeadlessConfig = HeadlessConfig {
   headlessResolution :: Maybe (Int, Int)
-  -- ^ Resolution for the headless browser. Defaults to @(1920, 1080)@.
+  -- ^ Resolution for the headless browser, specified as @(width, height)@. Defaults to @(1920, 1080)@.
   }
 
 -- | Default headless config.
@@ -95,7 +95,7 @@ data XvfbConfig = XvfbConfig {
   -- ^ Resolution for the virtual screen. Defaults to (1920, 1080)
 
   , xvfbStartFluxbox :: Bool
-  -- ^ Whether to start fluxbox window manager to go with the Xvfb session. fluxbox must be on the path
+  -- ^ Whether to start fluxbox window manager to go with the Xvfb session. @fluxbox@ must be on the path.
   }
 
 -- | Default Xvfb settings.

sandwich-webdriver/src/Test/Sandwich/WebDriver/Video.hs

@@ -1,14 +1,17 @@
 {-# LANGUAGE CPP #-}
 {-# LANGUAGE ConstraintKinds #-}
 
+-- | Functions for recording videos of browser windows.
+
 module Test.Sandwich.WebDriver.Video (
-  startVideoRecording
+  startBrowserVideoRecording
+  , startFullScreenVideoRecording
+
+  -- * Lower-level
+  , startVideoRecording
   , endVideoRecording
 
   -- * Helpers
-  , startFullScreenVideoRecording
-  , startBrowserVideoRecording
-
   , getXvfbSession
 
   -- * Configuration
@@ -19,6 +22,9 @@ module Test.Sandwich.WebDriver.Video (
   , defaultAvfoundationOptions
   , defaultGdigrabOptions
 
+  -- * Re-exports
+  , XvfbSession(..)
+
   -- * Types
   , BaseVideoConstraints
   ) where
@@ -52,7 +58,11 @@ type BaseVideoConstraints context m = (
 -- | Wrapper around 'startVideoRecording' which uses the full screen dimensions.
 startFullScreenVideoRecording :: (
   BaseVideoConstraints context m
-  ) => FilePath -> VideoSettings -> m ProcessHandle
+  )
+  -- | Output path
+  => FilePath
+  -> VideoSettings
+  -> m ProcessHandle
 startFullScreenVideoRecording path videoSettings = do
   sess <- getContext webdriver
   let maybeXvfbSession = getXvfbSession sess
@@ -66,16 +76,27 @@ startFullScreenVideoRecording path videoSettings = do
 -- | Wrapper around 'startVideoRecording' which uses WebDriver to find the rectangle corresponding to the browser.
 startBrowserVideoRecording :: (
   BaseVideoConstraints context m, W.WebDriver m
-  ) => FilePath -> VideoSettings -> m ProcessHandle
+  )
+  -- | Output path
+  => FilePath
+  -> VideoSettings
+  -> m ProcessHandle
 startBrowserVideoRecording path videoSettings = do
   (x, y) <- getWindowPos
   (w, h) <- getWindowSize
   startVideoRecording path (w, h, x, y) videoSettings
 
--- | Record video to a given path, for a given rectangle specified as (width, height, x, y).
+-- | Record video to a given path, for a given screen rectangle.
 startVideoRecording :: (
   BaseVideoConstraints context m
-  ) => FilePath -> (Word, Word, Int, Int) -> VideoSettings -> m ProcessHandle
+  )
+  -- | Output path
+  => FilePath
+  -- | Rectangle to record, specified as @(width, height, x, y)@
+  -> (Word, Word, Int, Int)
+  -> VideoSettings
+  -- | Returns handle to video process
+  -> m ProcessHandle
 startVideoRecording path (width, height, x, y) vs = do
   sess <- getContext webdriver
   let maybeXvfbSession = getXvfbSession sess

stack.yaml

@@ -30,9 +30,9 @@ packages:
 
 - ./demos/demo-basic
 - ./demos/demo-command-line-args
-- ./demos/demo-contexts
 - ./demos/demo-context-dependencies
 - ./demos/demo-context-nested
+- ./demos/demo-contexts
 - ./demos/demo-custom-exceptions
 - ./demos/demo-discover
 - ./demos/demo-fake-smtp-server
@@ -56,8 +56,9 @@ packages:
 - ./demos/demo-timing
 - ./demos/demo-timing-parallel
 - ./demos/demo-tui
-- ./demos/demo-webdriver
 - ./demos/demo-webdriver-landing
+- ./demos/demo-webdriver-nix
+- ./demos/demo-webdriver-normal
 - ./demos/demo-webdriver-pool
 - ./demos/demo-webdriver-positioning
 - ./demos/demo-webdriver-video