grunt-safaridriver

Controls Safari on OSX using the WebDriver interface via safaridriver without Selenium.

If you use a modern test driver like webdriverio, you will not need Selenium to run the tests, because the browser driver itself implements the WebDriver interface. This module provides a Grunt multi-task for installing, starting and stopping the safaridriver executable. You take care of maintaining the reasonably recent vewsion of OSX and Safari. Starting with Safari 10 on OS X El Capitan and macOS Sierra, Safari comes bundled with a new driver implementation that's maintained by the Web Developer Experience team at Apple. You might need to run safaridriver --enable to enable this feature.

This task, grunt-chromedriver and grunt-geckodriver can be used as a replacement for grunt-selenium-standalone for tasks like grunt-html-dom-snapshot, to simplify the whole scenario by removing Selenium and Java from the requirements.

Installation

You need node >= 10, npm and grunt >= 1.0.0 installed and your project build managed by a Gruntfile. If you have not used Grunt before, be sure to check out the [Getting Started] guide, as it explains how to create a Gruntfile as well as install and use Grunt plugins. Once you are familiar with that process, you may install this plugin with this command:

npm install grunt-safaridriver --save-dev

Configuration

Add the safaridriver entry with one or more tasks to the options of the grunt.initConfig method in Gruntfile.js:

grunt.initConfig({
  safaridriver: {
    default: {}
  }
});

Load the plugin:

grunt.loadNpmTasks('grunt-safaridriver');

Add use the task to start and stop the browser driver before and after the tests:

grunt.registerTask('default', ['safaridriver:default:start', ..., 'safaridriver:default:stop']);

Options

Default task options support the most usual usage scenario:

safaridriver: {
  default: {
    port: 4444,
    findAvailablePort: false,
    args: [],
    force: false
  }
}

port

Type: Number Default value: 4444

The port for the safaridriver to listen to. If findAvailablePort is set to true, this port will be used to start the search for a free port with.

findAvailablePort

Type: Boolean Default value: false

If set to true, the value of port will be used to start the search for a free port with.

args

Type: Array<String> Default value: []

Command-line arguments for the safaridriver executable. Available ones:

-p, --port  Port number the driver should use. If the server
            is already running, the port cannot be changed.
            If port 0 is specified, a default port will be used.
--enable    Applies configuration changes so that subsequent WebDriver
            sessions will run without further authentication.
--diagnose  Causes safaridriver to log diagnostic information for
            all sessions hosted by this instance. See the safaridriver(1)
            man page for more details about diagnostic logging.

force

Type: Boolean Default value: false

If set to true, it suppresses failures. Instead of making the Grunt fail, the errors will be written only to the console.

Events

If findAvailablePort is set to true, the actual chosen port can be read by:

grunt.config.get(`safaridriver.<task-name>.port`)

As soon es the browser driver process starts listening, an event will be triggered with the actually chosen port:

grunt.event.on(`safaridriver.<task-name>.listening`, port => {...})

Contributing

In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code using Grunt.

License

Copyright (c) 2020-2023 Ferdinand Prantl

Licensed under the MIT license.