Skip to content

Commit

Permalink
updated docs to v1
Browse files Browse the repository at this point in the history
  • Loading branch information
@beatfactor
beatfactor committed Aug 4, 2018
1 parent dd22942 commit 92ea22b
Show file tree
Hide file tree
Showing 25 changed files with 558 additions and 374 deletions.
160 changes: 40 additions & 120 deletions gettingstarted/browser-setup/chromedriver.md
View file
Original file line number Diff line number Diff line change
@@ -1,11 +1,39 @@
### ChromeDriver
## ChromeDriver

#### Overview
[ChromeDriver](https://sites.google.com/a/chromium.org/chromedriver/) is a standalone server which implements the W3C WebDriver wire protocol for Chromium. ChromeDriver is available for Chrome on Android and Chrome on Desktop (Mac, Linux, Windows and ChromeOS).
ChromeDriver is a standalone server which implements the [JSON Wire Protocol](https://github.com/SeleniumHQ/selenium/wiki/JsonWireProtocol) for Chromium, however it is currently in the process of transitioning to the W3C WebDriver spec.

It is available for Chrome on Android and Chrome on Desktop (Mac, Linux, Windows and ChromeOS).


#### Download

Binaries are available for download on the [ChromeDriver Downloads](https://sites.google.com/a/chromium.org/chromedriver/downloads) page, for various platforms.
ChromeDriver can be downloaded from the [ChromeDriver Downloads](http://chromedriver.chromium.org/downloads) page. Or you can use the [chromedriver](https://www.npmjs.com/package/chromedriver) NPM package as a dependency in your project:

<pre>$ npm install chromedriver --save-dev</pre>

#### Standalone Usage

Nightwatch can manage the ChromeDriver service automatically, as with other WebDriver services, such as GeckoDriver. To use ChromeDriver directly, add this to your `nightwatch.json`:

<pre><code class="language-javascript">{
<strong>"webdriver"</strong>: {
"server_path": "node_modules/.bin/chromedriver",
"cli_args": [
"--verbose"
],
"port": 9515
},

<strong>"test_settings"</strong> : {
"default" : {
"desiredCapabilities" : {
"browserName" : "chrome"
}
}
}
}
</code></pre>

#### Selenium Server Usage

Expand All @@ -23,134 +51,26 @@ If you're using ChromeDriver through Selenium Server, simply set the cli argumen
}
}</code></pre>

##### ChromeOptions
You can specify Chrome options or switches using the `chromeOptions` dictionary, under the `desiredCapabilities`. Refer to the [ChromeDriver website](https://sites.google.com/a/chromium.org/chromedriver/capabilities#TOC-chromeOptions-object) for a fill list of supported capabilities and options.



#### Standalone Usage

If you're only running your tests against Chrome, running ChromeDriver standalone is easier and slightly faster. Also there is no dependency on Java.

This requires a bit more configuration:<br><br>

##### 1) First, disable Selenium Server, if applicable:

<pre><code class="language-javascript">{
<strong>"selenium"</strong> : {
"start_process" : false
}
}
</code></pre>

Note that you still need to keep `start_session` set to true, if you intend to interact with the Selenium server (e.g. issue Webdriver commands).


##### 2) Configure the port and default path prefix.

ChromeDriver runs by default on port 9515. We also need to clear the `default_path_prefix`, as it is set by default to `/wd/hub`, which is what selenium is using.

<pre><code class="language-javascript">{
##### Example of detailed config
<pre><code class="language-javascript">{
<strong>"test_settings"</strong> : {
"default" : {
"selenium_port" : 9515,
"selenium_host" : "localhost",
"default_path_prefix" : "",

"desiredCapabilities": {
"browserName": "chrome",
"chromeOptions" : {
"desiredCapabilities" : {
"browserName" : "chrome",
"chromeOptions": {
"args" : ["--no-sandbox"]
},
"acceptSslCerts": true
"loggingPrefs": {"driver": "INFO", "server": "OFF", "browser": "INFO"}
}
}
}
}
</code></pre>

##### 3) Start the ChromeDriver server

The easiest way to manage the ChromeDriver process is by using the `chromedriver` [NPM package](https://www.npmjs.com/package/chromedriver), which is a third-party wrapper against the binary. This will abstract the downloading of the chromedriver binary and will make it easy to manage starting and stopping of the process.

You can add this to your `external globals` file, like so:

<pre><code class="language-javascript">
var chromedriver = require('chromedriver');
module.exports = {
before : function(done) {
chromedriver.start();

done();
},

after : function(done) {
chromedriver.stop();

done();
}
};
</code></pre>

#### Using a fixed ChromeDriver version

In some situations you may need to use a specific version of ChromeDriver. For instance, the CI server runs an older version of Chrome. Then you will need an older version of ChromeDriver.

Here's what your globals file might look like:
<br>
<pre><code class="language-javascript">
var chromedriver = require('chromedriver');
var path = require('path');
var driverInstanceCI;

function isRunningInCI() {
return this.test_settings.globals.integration;
}

function startChromeDriver() {
if (isRunningInCI.call(this)) {
var location = path.join(__dirname, '../bin/chromedriver-linux64-2.17');
driverInstanceCI = require('child_process').execFile(location, []);
return;
}

chromedriver.start();
}

function stopChromeDriver() {
if (isRunningInCI.call(this)) {
driverInstanceCI && driverInstanceCI.kill();
return;
}

chromedriver.stop();
}

module.exports = {
'ci-server' : {
integration : true
},

before : function(done) {
startChromeDriver.call(this);

done();
},

after : function(done) {
stopChromeDriver.call(this);

done();
}
};</code></pre>
<br><br>

Run your tests then with (on the CI server):

<pre><code class="language-bash">$ ./node_modules/.bin/nightwatch --env ci-server</code></pre>

#### ChromeOptions
You can specify Chrome options or switches using the `chromeOptions` dictionary, under the `desiredCapabilities`. Refer to the [ChromeDriver website](https://sites.google.com/a/chromium.org/chromedriver/capabilities#TOC-chromeOptions-object) for a fill list of supported capabilities and options.

#### Command line usage
##### Command line usage

<pre><code>$ ./bin/chromedriver -h
Usage: ./bin/chromedriver [OPTIONS]
Expand Down
16 changes: 9 additions & 7 deletions gettingstarted/browser-setup/edgedriver.md
View file
Original file line number Diff line number Diff line change
@@ -1,11 +1,15 @@
### Microsoft WebDriver
## Microsoft WebDriver

#### Overview
[Microsoft WebDriver](https://developer.microsoft.com/en-us/microsoft-edge/tools/webdriver/) is a standalone server which implements the W3C WebDriver wire protocol for the Edge browser. It is supported by Windows 10 and onwards.
[Microsoft WebDriver](https://developer.microsoft.com/en-us/microsoft-edge/tools/webdriver/) is a standalone server which implements the WebDriver protocol for the Edge browser. It is supported by Windows 10 and onwards.

#### Download

Binaries are available for download on the [Microsoft WebDriver](https://developer.microsoft.com/en-us/microsoft-edge/tools/webdriver/) homepage.
WebDriver for Microsoft Edge is now a Windows Feature on Demand. To install run the following in an elevated command prompt:

<pre>$ DISM.exe /Online /Add-Capability /CapabilityName:Microsoft.WebDriver~~~~0.0.1.0</pre>

More details about installation and usage documentation are available on the official [Microsoft WebDriver homepage](https://developer.microsoft.com/en-us/microsoft-edge/tools/webdriver/).

#### Selenium Server Usage

Expand Down Expand Up @@ -35,8 +39,6 @@ If you're using Microsoft WebDriver through Selenium Server, simply set the cli
}</code></pre>




#### Standalone Usage

If you're only running your tests against Edge, running the EdgeDriver standalone can be slightly faster. Also there is no dependency on Java.
Expand Down Expand Up @@ -87,5 +89,5 @@ Full command line usage:
Usage:
MicrosoftWebDriver.exe --host=<HostName> --port=<PortNumber> --package=<Package> --verbose</code></pre>

#### Implementation Status
EdgeDriver is not yet feature complete, which means it does not yet offer full conformance with the WebDriver standard or complete compatibility with Selenium. Implementation status can be tracked on the [Microsoft WebDriver homepage](https://developer.microsoft.com/en-us/microsoft-edge/platform/documentation/webdriver-commands/).
##### Implementation Status
EdgeDriver is not yet feature complete, which means it does not yet offer full conformance with the WebDriver standard or complete compatibility with Selenium. Implementation status can be tracked on the [Microsoft WebDriver homepage](https://docs.microsoft.com/en-us/microsoft-edge/webdriver).
39 changes: 33 additions & 6 deletions gettingstarted/browser-setup/gecko-driver.md
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
### GeckoDriver
## GeckoDriver

#### Overview
[GeckoDriver](https://github.com/mozilla/geckodriver) is a standalone application used to interact with Gecko-based browsers, such as Firefox. It is written in Rust and maintained by Mozilla.
Expand All @@ -7,11 +7,38 @@ Starting with Firefox 48, GeckoDriver is the only way to automate Firefox, the l

#### Download

Binaries are available for download on the [GeckoDriver Releases](https://github.com/mozilla/geckodriver/releases) page on GitHub, for various platforms.
GeckoDriver can be downloaded from the [Releases page](https://github.com/mozilla/geckodriver/releases) on GitHub. Release notes are also available there. Or you can use the [geckodriver](https://www.npmjs.com/package/geckodriver) NPM package as a dependency in your project:

<pre>$ npm install geckodriver --save-dev</pre>

Selenium 2.x users are advised to use version __v0.9__, whereas Selenium 3 users should use the latest version.

#### Usage
#### Standalone Usage

Nightwatch can manage the GeckoDriver service automatically, as with other WebDriver services, such as ChromeDriver. To use GeckoDriver directly, add this to your `nightwatch.json`:

<pre><code class="language-javascript">{
<strong>"webdriver"</strong>: {
"start_process" : true,
"server_path": "./bin/geckodriver-0.21",
"cli_args": [
"--log", "debug"
],
"port": 4444
},

<strong>"test_settings"</strong> : {
"default" : {
"desiredCapabilities": {
"browserName" : "firefox",
"acceptInsecureCerts": true
}
}
}
}
</code></pre>

#### Usage with Selenium Server

If you're using GeckoDriver through Selenium Server, simply set the cli argument `"webdriver.gecko.driver"` to point to the location of the binary file. E.g.:

Expand Down Expand Up @@ -53,11 +80,11 @@ OPTIONS:
-p, --port <PORT> Port to use for WebDriver server (default: 4444)
</code></pre>

#### Firefox Capabilities
##### Firefox Capabilities
GeckoDriver supports a capability named `firefoxOptions` which takes Firefox-specific preference values. Details are available on the GeckoDriver GitHub page: https://github.com/mozilla/geckodriver#firefox-capabilities.

#### Firefox Profile
##### Firefox Profile
Specifying the firefox profile can be done by setting the `profile` property in the `firefoxOptions` dictionary, as detailed above. This can be the base64-encoded zip of a profile directory and it may be used to install extensions or custom certificates.

#### Implementation Status
##### Implementation Status
GeckoDriver is not yet feature complete, which means it does not yet offer full conformance with the WebDriver standard or complete compatibility with Selenium. Implementation status can be tracked on the [Marionette MDN page](https://developer.mozilla.org/en-US/docs/Mozilla/QA/Marionette/WebDriver/status).
36 changes: 21 additions & 15 deletions gettingstarted/configuration/config-basic-settings.md
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
### Basic settings
## Basic Settings

<table class="table table-bordered table-striped">
<thead>
Expand All @@ -16,6 +16,18 @@
<td>none</td>
<td>An array of folders (excluding subfolders) where the tests are located.</td>
</tr>
<tr>
<td>webdriver</td>
<td>object</td>
<td></td>
<td>An object containing WebDriver related configuration options. See the next section for details.</td>
</tr>
<tr>
<td>test_settings</td>
<td>object</td>
<td></td>
<td>This object contains all the test related options. See below for details.</td>
</tr>
<tr>
<td>output_folder <br><span class="optional">Optional</span></td>
<td>string</td>
Expand Down Expand Up @@ -46,18 +58,6 @@
<td>none</td>
<td>Location of an external globals module which will be loaded and made available to the test as a property <code>globals</code> on the main client instance. <br><br>Globals can also be defined/overwritten inside a <code>test_settings</code> environment.</td>
</tr>
<tr>
<td>selenium <br><span class="optional">Optional</span></td>
<td>object</td>
<td></td>
<td>An object containing Selenium Server related configuration options. See below for details.</td>
</tr>
<tr>
<td>test_settings</td>
<td>object</td>
<td></td>
<td>This object contains all the test related options. See below for details.</td>
</tr>
<tr>
<td>live_output <br><span class="optional">Optional</span></td>
<td>boolean</td>
Expand All @@ -84,11 +84,17 @@
<br><br>Example: <code>"test_workers" : {"enabled" : true, "workers" : "auto"}</code></td>
</tr>
<tr>
<td>test_runner <br><span class="optional">Optional</span> <span class="optional">since v0.8.0</span></td>
<td>test_runner <br><span class="optional">Optional</span></td>
<td>string|object</td>
<td>"default"</td>
<td>Specifies which test runner to use when running the tests. Values can be either `default` (built in nightwatch runner) or `mocha`.
<td>Specifies which test runner to use when running the tests. Values can be either `default` (built-in nightwatch runner) or `mocha`.
<br><br>Example: <code>"test_runner" : {"type" : "mocha", "options" : {"ui" : "tdd"}}</code></td>
</tr>
<tr>
<td>unit_tests_mode <br><span class="optional">Optional</span></td>
<td>boolean</td>
<td>false</td>
<td>Controls whether to run tests in unit testing mode, which means the session will not automatically be created.</td>
</tr>
</tbody>
</table>
2 changes: 1 addition & 1 deletion gettingstarted/configuration/config-test-settings.md
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
### Test settings
## Test Settings

Below are a number of settings that will be passed to the Nightwatch instance. You can define multiple sections (environments) of test settings so you could overwrite specific values per environment.

Expand Down
Loading

0 comments on commit 92ea22b

Please sign in to comment.