Run Protractor with grunt (grunt-angular-protractor)

Run protractor with grunt task runner

Getting Started

This plugin requires Grunt ~0.4.5

npm install grunt-angular-protractor --save-dev

Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:

grunt.loadNpmTasks('grunt-angular-protractor');

The "angular_protractor" task

Overview

In your project's Gruntfile, add a section named angular_protractor to the data object passed into grunt.initConfig().

IMPORTANT: In the Task options you can write the same config like the protractor configFile.js. You overwrite the configFile.

Example 1

var path = require('path');
grunt.initConfig({
  angular_protractor: {
      task1: {
          configFile: path.join(__dirname, 'tests', 'task1', 'conf.js'),
          options: {            
              specs: [
                  path.join(__dirname, 'tests', 'task1', '*_e2e.js')
              ]
          },
          dest: path.join(__dirname, 'build', 'task1-config.js')
      },
      task2: {
          configFile: path.join(__dirname, 'tests', 'task2', 'conf.js'),
          options: {
              specs: [
                  path.join(__dirname, 'tests', 'task2', '*_e2e.js')
              ]
          },
          dest: path.join(__dirname, 'build', 'task2-config.js')
      }
  }
});

Example 2

var path = require('path');
grunt.initConfig({
  angular_protractor: {
      task1: {
          configFile: path.join(__dirname, 'tests', 'task1', 'conf.js'),
          protractorBinaries: path.join(__dirname, 'node_modules', 'protractor', 'bin'),
          keepAlive: false,
          noColor: false,
          debug: false,
          webdriverManagerUpdate: false,
          options: {            
               directConnect: false,
               multiCapabilities: [
                   {
                       browserName: 'chrome',
                       logName: 'Chrome',
                       count: 1,
                       shardTestFiles: true,
                       maxInstances: 1,
                       specs: ['*_e2e.js']
                   },
                   {
                       browserName: 'firefox',
                       name: 'Firefox Job',
                       logName: 'firefox',
                       count: 1,
                       shardTestFiles: false,
                       maxInstances: 2,
                       specs: ['*_e2e.js']
                   }
               ],
               framework: 'jasmine2',
               jasmineNodeOpts: {
                   defaultTimeoutInterval: 30000
               }
          },
          dest: path.join(__dirname, 'build', 'task1-config.js')
      }
  }
});

Grunt options

configFile (optional)

Type: String Default value: ``

Path must be absolute to the configFile. The configFile is the same as the protractor configFile. Example: tests/conf/configFile.js

protractorBinaries (optional)

Type: String Default value: ``

Absolute Path to your owb protractor binaries. Example: path.join(__dirname, 'node_modules', 'protractor', 'bin')

webdriverManagerUpdate (optional)

Type: Boolean Default value: false

Update the webdriver with the webdriver manager before protractor started.

keepAlive (optional)

Type: Boolean Default value: false

Keep build alive. Usefull for tests and watcher.

noColor (optional)

Type: Boolean Default value: false

Disable colored output with the --no-color flag.

debug (optional)

Type: Boolean Default value: false

Enable debugging mode with the --debug flag.

dest (optional)

Type: String Default value: ``

Path must be absolute. The File is the generated configFile for Protractor that's called with Protractor. Use here a tmp folder and clean it after each build.

Protractor options

options

Type: Object Default value: ``

Match each protractor object.key to the configFile that's executable with protractor.

options.seleniumServerJar (optional)

Type: String Default value: ``

seleniumServerJar - to start a standalone Selenium Server locally

The location of the standalone Selenium Server jar file, relative to the location of this config. If no other method of starting Selenium Server is found, this will default to node_modules/protractor/selenium/selenium-server...

options.seleniumPort (optional)

Type: Number Default value: ``

seleniumPort

The port to start the Selenium Server on, or null if the server should find its own unused port. Ignored if seleniumServerJar is null.

options.seleniumArgs (optional)

Type: Array Default value: ``

seleniumArgs

Additional command line options to pass to selenium. For example, if you need to change the browser timeout, use seleniumArgs: ['-browserTimeout=60'] Ignored if seleniumServerJar is null.

options.chromeDriver (optional)

Type: String Default value: ``

chromeDriver

ChromeDriver location is used to help find the chromedriver binary. This will be passed to the Selenium jar as the system property webdriver.chrome.driver. If null, Selenium will attempt to find ChromeDriver using PATH.

options.seleniumAddress (optional)

Type: String Default value: ``

seleniumAddress - to connect to a Selenium Server which is already running

The address of a running Selenium Server. If specified, Protractor will connect to an already running instance of Selenium. This usually looks like seleniumAddress: 'http://localhost:4444/wd/hub'

options.sauceUser (optional)

Type: String Default value: ``

seleniumAddress - to use remote browsers via Sauce Labs

If sauceUser are specified, seleniumServerJar will be ignored. The tests will be run remotely using Sauce Labs.

options.sauceKey (optional)

Type: String Default value: ``

sauceKey - to use remote browsers via Sauce Labs

If sauceKey are specified, seleniumServerJar will be ignored. The tests will be run remotely using Sauce Labs.

options.sauceAgent (optional)

Type: String Default value: ``

sauceAgent - to use remote browsers via Sauce Labs

Use sauceAgent if you need customize agent for https connection to saucelabs.com (i.e. your computer behind corporate proxy)

options.sauceSeleniumAddress (optional)

Type: String Default value: ``

sauceSeleniumAddress - to use remote browsers via Sauce Labs

Use sauceSeleniumAddress if you need to customize the URL Protractor uses to connect to sauce labs (for example, if you are tunneling selenium traffic through a sauce connect tunnel). Default is ondemand.saucelabs.com:80/wd/hub

options.directConnect (optional)

Type: Boolean Default value: ``

directConnect - to connect directly to Drivers

If true, Protractor will connect directly to the browser Drivers at the locations specified by chromeDriver and firefoxPath. Only Chrome and Firefox are supported for direct connect.

options.firefoxPath (optional)

Type: String Default value: ``

firefoxPath - to connect directly to Drivers

Path to the firefox application binary. If null, will attempt to find firefox in the default locations.

options.specs (optional)

Type: Array.String Default value: ``

specs

Spec patterns are relative to the location of this config.

options.exclude (optional)

Type: Array.String Default value: ``

exclude

Patterns to exclude.

options.suites (optional)

Type: Object Default value: ``

suites

Alternatively, suites may be used. When run without a command line parameter, all suites will run. If run with --suite=smoke or --suite=smoke,full only the patterns matched by the specified suites will run.

options.capabilities (optional)

Type: Object Default value: ``

capabilities

Protractor can launch your tests on one or more browsers. If you are testing on a single browser, use the capabilities option. If you are testing on multiple browsers, use the multiCapabilities array. For a list of available capabilities, see https://github.com/SeleniumHQ/selenium/wiki/DesiredCapabilities In addition, you may specify count, shardTestFiles, and maxInstances.

options.capabilities.browserName (optional)

Type: String Default value: ``

capabilities.browserName

Name of the browser.

options.capabilities.name (optional)

Type: String Default value: ``

capabilities.name

Name of the process executing this capability. Not used directly by protractor or the browser, but instead pass directly to third parties like SauceLabs as the name of the job running this test

options.capabilities.logName (optional)

Type: String Default value: ``

capabilities.logName

User defined name for the capability that will display in the results log Defaults to the browser name

options.capabilities.count (optional)

Type: Number Default value: 1

capabilities.count

Number of times to run this set of capabilities (in parallel, unless limited by maxSessions). Default is 1.

options.capabilities.shardTestFiles (optional)

Type: Boolean Default value: false

capabilities.shardTestFiles

If this is set to be true, specs will be sharded by file (i.e. all files to be run by this set of capabilities will run in parallel). Default is false.

options.capabilities.maxInstances (optional)

Type: Number Default value: 1

capabilities.maxInstances

Maximum number of browser instances that can run in parallel for this set of capabilities. This is only needed if shardTestFiles is true. Default is 1.

options.capabilities.specs (optional)

Type: Array.String Default value: ``

capabilities.specs

Additional spec files to be run on this capability only.

options.capabilities.exclude (optional)

Type: Array.String Default value: ``

capabilities.exclude

Spec files to be excluded on this capability only.

options.capabilities.seleniumAddress (optional)

Type: String Default value: ``

capabilities.seleniumAddress

Override global seleniumAddress on this capability only.

options.multiCapabilities (optional)

Type: Array.Object Default value: ``

multiCapabilities

If you would like to run more than one instance of WebDriver on the same tests, use multiCapabilities, which takes an array of capabilities. If this is specified, capabilities will be ignored.

options.getMultiCapabilities (optional)

Type: Default value:

getMultiCapabilities

If you need to resolve multiCapabilities asynchronously (i.e. wait for server/proxy, set firefox profile, etc), you can specify a function here which will return either multiCapabilities or a promise to multiCapabilities. If this returns a promise, it is resolved immediately after beforeLaunch is run, and before any driver is set up. If this is specified, both capabilities and multiCapabilities will be ignored.

options.maxSessions (optional)

Type: Number Default value: -1

maxSessions

Maximum number of total browser sessions to run. Tests are queued in sequence if number of browser sessions is limited by this parameter. Use a number less than 1 to denote unlimited. Default is unlimited.

options.baseUrl (optional)

Type: String Default value: ``

baseUrl

A base URL for your application under test. Calls to protractor.get() with relative paths will be prepended with this.

options.rootElement (optional)

Type: String Default value: body

rootElement

CSS Selector for the element housing the angular app - this defaults to body, but is necessary if ng-app is on a descendant of .

options.allScriptsTimeout (optional)

Type: Number Default value: 11000

allScriptsTimeout

The timeout in milliseconds for each script run on the browser. This should be longer than the maximum time your application needs to stabilize between tasks.

options.getPageTimeout (optional)

Type: Number Default value: 10000

getPageTimeout

How long to wait for a page to load.

options.beforeLaunch (optional)

Type: Function Default value: ``

beforeLaunch

A callback function called once configs are read but before any environment setup. This will only run once, and before onPrepare. You can specify a file containing code to run by setting beforeLaunch to the filename string.

beforeLaunch: function() {
    // At this point, global variable 'protractor' object will NOT be set up,
    // and globals from the test framework will NOT be available. The main
    // purpose of this function should be to bring up test dependencies.
}

options.onPrepare (optional)

Type: Function Default value: ``

onPrepare

A callback function called once protractor is ready and available, and before the specs are executed. If multiple capabilities are being run, this will run once per capability. You can specify a file containing code to run by setting onPrepare to the filename string.

onPrepare: function() {
    // At this point, global variable 'protractor' object will be set up, and
    // globals from the test framework will be available. For example, if you
    // are using Jasmine, you can add a reporter with:
    //     jasmine.getEnv().addReporter(new jasmine.JUnitXmlReporter(
    //         'outputdir/', true, true));
    //
    // If you need access back to the current configuration object,
    // use a pattern like the following:
    //     browser.getProcessedConfig().then(function(config) {
    //       // config.capabilities is the CURRENT capability being run, if
    //       // you are using multiCapabilities.
    //       console.log('Executing capability', config.capabilities);
    //     });
}

options.onComplete (optional)

Type: Function Default value: ``

onComplete

A callback function called once tests are finished.

onComplete: function() {
    // At this point, tests will be done but global objects will still be
    // available.
}

options.onCleanUp (optional)

Type: Function Default value: ``

onCleanUp

A callback function called once the tests have finished running and the WebDriver instance has been shut down. It is passed the exit code (0 if the tests passed). This is called once per capability.

options.afterLaunch (optional)

Type: Function Default value: ``

afterLaunch

A callback function called once all tests have finished running and the WebDriver instance has been shut down. It is passed the exit code (0 if the tests passed). This is called only once before the program exits (after onCleanUp).

options.params (optional)

Type: Object Default value: ``

params

The params object will be passed directly to the Protractor instance, and can be accessed from your test as browser.params. It is an arbitrary object and can contain anything you may need in your test. This can be changed via the command line as: --params.login.user 'Joe'

params: {
        login: {
            user: 'Jane',
            password: '1234'
        }
    }
}

options.resultJsonOutputFile (optional)

Type: String Default value: ``

resultJsonOutputFile

If set, protractor will save the test output in json format at this path. The path is relative to the location of this config.

options.restartBrowserBetweenTests (optional)

Type: Boolean Default value: false

restartBrowserBetweenTests

If true, protractor will restart the browser between each test. CAUTION: This will cause your tests to slow down drastically.

options.framework

Type: String Default value: jasmine2

framework

Test framework to use. This may be one of: jasmine, jasmine2, cucumber, mocha or custom.

When the framework is set to "custom" you'll need to additionally set frameworkPath with the path relative to the config file or absolute framework: 'custom', frameworkPath: './frameworks/my_custom_jasmine.js', See github.com/angular/protractor/blob/master/lib/frameworks/README.md to comply with the interface details of your custom implementation.

Jasmine and Jasmine2 are fully supported as test and assertion frameworks. Mocha and Cucumber have limited support. You will need to include your own assertion framework (such as Chai) if working with Mocha.

options.jasmineNodeOpts (optional)

Type: Object Default value: ``

Jasmine1 (jasmineNodeOpts)

See the full list at https://github.com/juliemr/minijasminenode/tree/jasmine1

jasmineNodeOpts: {
    // If true, display spec names.
    isVerbose: false,
    // If true, print colors to the terminal.
    showColors: true,
    // If true, include stack traces in failures.
    includeStackTrace: true,
    // Default time to wait in ms before a test fails.
    defaultTimeoutInterval: 30000
}

Jasmine2 (jasmineNodeOpts)

See https://github.com/jasmine/jasmine-npm/blob/master/lib/jasmine.js for the exact options available.

jasmineNodeOpts: {
    // If true, print colors to the terminal.
    showColors: true,
    // Default time to wait in ms before a test fails.
    defaultTimeoutInterval: 30000,
    // Function called to print jasmine results.
    print: function() {},
    // If set, only execute specs whose names match the pattern, which is
    // internally compiled to a RegExp.
    grep: 'pattern',
    // Inverts 'grep' matches
    invertGrep: false
}

Mocha (mochaOpts)

See the full list at http://mochajs.org/

mochaOpts: {
    ui: 'bdd',
    reporter: 'list'
}

Cucumber (cucumberOpts)

Options to be passed to Cucumber.

cucumberOpts: {
    // Require files before executing the features.
    require: 'cucumber/stepDefinitions.js',
    // Only execute the features or scenarios with tags matching @dev.
    // This may be an array of strings to specify multiple tags to include.
    tags: '@dev',
    // How to format features (default: progress)
    format: 'summary'
}

Release History

| Version | Description | |:------------|-------------------------------------------------| | 0.0.4 | Add missing grunt options | | 0.0.1 | Init |