nightwatch.js是一個測試web app和web 站點的自動化測試架構， 使用node.js編寫， 基于selenium webdriver api.
它是一個完整的浏覽器端真實使用者場景測試解決方案， 緻力于簡化繼續內建和編寫自動化測試。
nightwatch got its name from the famous painting the night watch by dutch painter rembrandt van rijn. the masterpiece is prominently displayed in the rijksmuseum, in amsterdam - the netherlands.
selenium 是一個直接運作在浏覽器中的非常流行的綜合測試工具集， 最初為java 語言編寫， 現在已經支援許多語言。
selenium的主要項目:
* selenium ide
* selenium remote control
* selenium webdriver
* selenium grid
nightwatch uses the selenium webdriver, specifically the webdriver wire protocol to perform the browser automation related tasks.
nightwatch 使用selenium webdriver， 特别是webdriver wire protocol 來執行浏覽器自動化測試相關任務。
nightwatch works by sending http requests to the selenium server with the right parameters and interpreting the response. the restful api protocol is defined by the selenium jsonwireprotocol. see below for an example workflow for browser initialization.
nightwatch 發送通過 http 請求發送響應的參數到 selenium 伺服器，并解析伺服器響應。restful api 文檔見selenium jsonwireprotocol 。浏覽器初始化流程見下圖。
大部分情況下， nightwatch 執行一條指令或斷言，至少要發送2個請求到 selenium 伺服器。 第一個用來定位元素，可以用 css 選擇器或者xpath 表達式。 第二個用來在選中的元素上執行指令或斷言操作。
from nodejs.org:
“node.js is a platform built on chrome’s javascript runtime for easily building fast, scalable network applications. node.js uses an event-driven, non-blocking i/o model that makes it lightweight and efficient, perfect for data-intensive real-time applications that run across distributed devices.”
主流作業系統的安裝包都可以在nodejs.org上找到。
使用 npm 安裝最新的 nightwatch， 在指令行運作:
selenium webdriver server 是一個簡單的 java servlet 程式，分别運作在本地機器上和你要進行測試的浏覽器上。(todo 真的是浏覽器上？)
download selenium
download the latest version of the selenium-server-standalone-{version}.jar file from the selenium downloads page and place it on the computer with the browser you want to test. in most cases this will be on your local machine and typically inside your project’s source folder.
到selenium downloads page下載下傳最新版的selenium-server-standalone-{version}.jar 包， (todo)具體放在哪裡， 等我試一試再說。
也可以通過 npm 安裝 selenium server：
a good practice is to create a separate subfolder (e.g. bin) and place it there as you might have to download other driver binaries if you want to test multiple browsers.
running selenium automatically
如果伺服器和nightwatch 運作在同一台機器上， nightwatch test runner可以啟動和停止selenium 伺服器。
running selenium manually
to run the selenium server manually, from the directory with the jar run the following:
要手動啟動 server 伺服器， 在 jar 包所在目錄執行:
更多關于運作 selenium 伺服器的資訊參考:
http://code.google.com/p/selenium/wiki/remotewebdriverserver
要擷取幫助資訊, 執行:
測試需要一個配置檔案， 預設會使用目前目錄下的 nightwatch.json 檔案。nightwatch.json 詳細配置如下：
name
type
default
description
src_folders
string|array
none
測試代碼目錄(不包含子目錄)
output_folder (optional)
string
tests_output
生成的測試報告存放目錄
custom_commands_path (optional)
location(s) where custom commands will be loaded from.
custom_assertions_path (optional)
自定義斷言路徑
page_objects_path (optional since v6.0.1)
location(s) where page object files will be loaded from.
globals_path (optional)
外部子產品路徑，為測試一共全局變量. 也可在test_settings中重寫
selenium (optional)
object
selenium server相關的設定
test_settings (optional)
與測試相關的測試，下面有較長的描述
live_output (optional)
boolean
false
是否緩存并持續輸出結果
disable_colors (optional)
控制指令行輸出是否帶有高亮顔色
parallel_process_delay (optional)
integer
10
在并行模式下啟動子程序的時間，機關毫秒
test_workers
boolean|object
是否為運作單個檔案測試啟動并行模式，如果設定為true，會進入并行模式，并自動設定線程數。如果設定為對象，要指定enable和workers參數,workers接受數值和’auto’。 例如：”test_workers” : {“enabled” : true, “workers” : “auto”}
test_runner (optional)
string|object
“default”
用什麼工具運作測試。值可以是”default”或”mocha”. 例如：”test_runner” : {“type” : “mocha”, “options” : {“ui” : “tdd”}}
如下是 selenium 的配置選項。nightwatch可以自動管理 selenium 服務程序，以便你專注于測試工作。
如果要啟用 selenium自啟動，設定 start_process 為true 并設定 server_path 值為 selenium jar包路徑。
start_process
是否啟用 selenium自啟動
start_session
true
是否自動啟動 selenium session.
server_path
selenium jar 包路徑。如果設定了 start_process 字段，必須設定此字段。例如： node_modules/selenium-server/lib/runner/selenium-server-standalone-2.53.0.jar
log_path
string|boolean
selenium 生成的 output.log 檔案存放位置，預設為目前目錄下。設定false可以禁用 selenium 日志。
host
127.0.0.1
設定 selenium 監聽位址。不常用到，除非指定了 start_process 為true。
port
4444
設定 selenium 監聽端口
cli_args
一系列傳遞給 selenium 的指令行參數。 有許多選項可以設定, 例如:
webdriver.firefox.profile： 預設情況下會為每個會話建立一個firefox配置檔案，如果想要使用現有配置檔案，在這裡指定檔案名。firefox驅動參數的完整清單見這裡 。
webdriver.chrome.driver: nightwatch 也可以在 chrome 上運作測試，如果要在 chrome 上運作測試需要下載下傳 chromedriver binary 并為此字段設定 chromedriver 路徑。同時要在desiredcapabilities 對象配置中指定 browsername值為 “chrome”。 更多資訊參考chromedriver website。
webdriver.ie.driver: nightwatch同時也支援internet explorer，要在ie中運作測試，需要下載下傳 ie driver binary 并為此字段設定 ie driver 路徑。同時要在 desiredcapabilities 對象配置中指定 browsername值為 “internet explorer”。
下面是一些nightwatch 執行個體的配置資訊。可以配置多個不同的配置對象，模拟多種測試環境。:
隻有”default”配置是必須的，其他配置可以按需要覆寫default中的配置資訊。
測試環境可以通過 -env 參數傳遞給 nightwatch：
launch_url
測試時要加載的首頁url, 如果有多個測試環境，可以分别指定url。
selenium_host
localhost
指定 selenium server 接受的 hostname/ip。
selenium_port
指定 selenium server 接受的端口。
silent
是否顯示 selenium 指令日志。
output
rue
是否在指令行顯示完整輸出。
disable_colors
指令行輸出是否高亮。
firefox_profile
已經棄用
chrome_driver
ie_driver
screenshots
當發生錯誤時 selenium 會生成螢幕截圖。如果 on_failure 設定為 true, 發生錯誤或沒有通過測試時也生成螢幕截圖。
從 v0.7.5 版本開始，可以為”on_error”字段設定false來禁止錯誤時生成截圖。
例如:“screenshots”:{“enabled”:true,”on_failure”:true,”on_error”: false,”path”: “”}
username
萬一 selenium 需要憑證，該字段用來生成 authorization header。值可以是系統變量，例如:”username” : “${sauce_username}”
access_key
與 username 一樣用于生成 authorization header。像 username 一樣，值也可以是系統變量。
proxy
使用代理通路 selenium server。支援 http, https, socks(v5), socks5, sock4, 和 pac。使用node-proxy-agent。example: http://user:pass@host:port
desiredcapabilities
在建立 session 之前傳遞給 selenium webdriver，可以用來指定浏覽器名稱和其他功能。例如：“desiredcapabilities” : {“browsername” : “firefox”, “acceptsslcerts” :true}。 完整的功能清單在這裡。
globals
在測試代碼中可以通路的全局變量，并且每次切換測試環境時可以重寫該值。例如: *”globals” :{“myglobal” : “some_global”}
exclude
array
不包含的檔案夾，接受字元串或模式字元串(relative to the main source folder)。例如：”exclude” : [“excluded-folder”] 或 :”exclude” : [“test-folder/*-smoke.js”]
filter
接受字元串或模式字元串，與之不比對的檔案會被忽略。
log_screenshot_data
是否在日志(verbose模式)中記錄螢幕截圖的base64編碼資訊。
use_xpath
是否用 xpath 做為預設的元素選擇政策。
作用與 selenium 配置中的 cli_args 相同。 你可以在不同的測試環境配置中覆寫 selenium 中的配置。
end_session_on_fail
在測試終止的時候，自動關閉會話，通常會在斷言失敗後觸發。
skip_testcases_on_fail
是否在任意測試用例測試失敗後，跳過剩餘的測試用例。
output_folder
生成的測試報告存放目錄, 該值覆寫 basic settings 中的配置， 也可以設定為 false 不生成報告。
persist_globals
weather or not to persist use the same object instance for holding globals between testsuite runs or a (deep) copy of it.
通過css選擇器在頁面中定位元素，nightwatch 使得編寫 end-to-end 自動測試非常簡單。
在你的項目中建立一個檔案夾，比如tests，其中的檔案會被 nightwatchcreate 加載并運作測試，一個最基本的測試如下所示：
當你想要停止測試時注意總是要調用 end() 方法，如此 selenium 會話才會正确的停止。
如果需要，一段測試也可以分為多步：
測試代碼也可以以這種格式來寫：
nightwatch 也支援 xpath。 調用 usexpath() 使用 xpath 規則選取元素。要退回 css 規則， 再調用 usecss() 方法。
如果要用 xpath 做為預設的元素選擇政策，在配置檔案中設定 “use_xpath”為true。
從 nightwatch0.7 版本開始， 引入了新的 bdd風格的斷言庫，大大提升了靈活性和代碼的可讀性。
expect 斷言是 chai 架構 expect api 的子集，在此對元素類型也能使用。 例如：
expect 接口為斷言提供了靈活流暢的短語，比之前的接口有顯著的改善。 唯一的缺點是沒法鍊式調用斷言，并且自定義消息目前也不支援。
except 完整的 api 點這裡。
nightwatch 為測試提供了 before/after, beforeeach/aftereach 鈎子。
before 和 after 鈎子會在每個測試套件運作前後執行。beforeeach 和 aftereach 則會在每個測試用例(測試步驟)執行前後執行。
所有鈎子函數都接收一個 nightwatch 執行個體做為參數。
example:
上例中方法的調用順序如下：
before(), beforeeach(), “step one”, aftereach(), beforeeach(), “step two”, aftereach(), after()
所有的 before[each] 和 after[each] 鈎子函數對異步操作同樣适用，用于異步操作時會給函數傳遞第二個參數 callback .
done 方法必須在異步操作完成時之行，否則會抛出一個 timeout 錯誤.
example：
指定調用 done 方法的逾時時間
預設情況下，done 方法的逾時時間設定為 10 秒(2秒用來之行單元測試)。在某些情況下，10 秒鐘不夠而且會出現 timeout 錯誤。 你可以在全局變量配置檔案中自己設定 asynchooktimeout 屬性來指定該值，機關為毫秒。 例子。
強制測試失敗
要強制使測試失敗， 需要在調用 done 方法時，傳入一個 error 對象。
大多數時候，使用外部檔案定義全局變量是比較好的實踐。為 globals_path 屬性指定外部檔案路徑， 而不是在 nightwatch.json 配置中定義全局變量。
還可以在應用每個 environment 之前重寫外部檔案中的變量值。
全局鈎子
之前提到的鈎子函數在全局範圍也同樣适用，outside the scope of the test。下面的例子給出了詳細資訊。 在這種情況下，beforeeach 和 aftereach 作用于一個測試集(i.e. test file)。
全局設定
globals檔案有許多屬性用于控制測試流程。下面的例子給出了詳細資訊：
nightwatch 包含了一個指令行工具，可以非常簡單的運作測試并輸出有用的資訊。根據你安裝的方式，有多種不同的指令形式。
global
如果你是全局安裝 nightwatch (使用 -g 選項)，nightwatch 在所有目錄下都是可用的。
project specific
如果 nightwatch 是以工程的依賴形式安裝， 要在 node_modules/.bin/ 目錄下才能使用 nightwatch 指令。
linux and macosx:
windows:
建立一個 nightwatch.js 檔案并輸入下面這行代碼:
然後執行：
tests source
可選的 source 選項可以指定一個或多個檔案，也可以直接指定一個檔案夾，該選項獨立于 src_folders 設定。
example - single test:
example - 2 individual tests:
example - 1 individual test and 1 folder:
指令行選項
shortname
–config
-c
./nightwatch.json
nightwatch.json 檔案路徑
–output
-o
junit 生成的報告儲存路徑.
–reporter
-r
junit
指定預定義的生成報告的工具，或是自定義用于生成報告的檔案路徑
–env
-e
指定測試環境，可以覆寫 nightwatch.json 中的值
–verbose
是否在指令行輸出詳細資訊
–version
-v
是否顯示版本号
–test
-t
運作指定的測試檔案，預設會運作跟目錄下所有測試檔案
–testcase
與test選項一同使用，指定要運作的測試用例
–group
-g
運作指定組中(子目錄)中的所有測試，測試檔案按目錄分組
–skipgroup
-s
跳過指定的一個或多個(以逗号分隔)測試組
–filter
-f
指定一個模式字元串用于過濾測試檔案
–tag
-a
使用tag過濾測試子產品，隻有帶有相應标簽的測試子產品才被執行
–skiptags
指定跳過帶有相應标簽的子產品，多個以逗号隔開
–retries
retries failed or errored testcases up to the specified number of times. retrying a testcase will also retry the beforeeach and aftereach hooks, if any.
–suiteretries
retries failed or errored testsuites (test modules) up to the specified number of times. retrying a testsuite will also retry the before and after hooks (in addition to the global beforeeach and aftereach respectively), if any are defined on the testsuite.
nightwatch 允許你以集合的形式組織測試腳本， 并按需運作這些測試集。要把測試檔案放在同一檔案夾下就可以将它們組合起來，檔案夾的名稱就是測試集的名稱。
如果隻想測試 smoketests ， 運作如下指令：
如果要跳過 smoketests， 運作如下指令：
要跳過多個測試集， 以逗号分隔：
你也可以選擇用标簽來管理要運作哪些測試， 那樣的話，一個測試可能屬于多個标簽。例如：有一個 login 測試即屬于 login 标簽，又屬于 sanity 标簽。
使用 –flag 指令行選項決定運作那個标簽下的測試：
指定多個标簽:
要跳過指定标簽， 使用 –skiptags 選項：
要跳過多個标簽， 用逗号隔開:
要阻止某個子產品執行測試， 隻需要設定 disable 屬性為true ：
在明确某些子產品會測試失敗時，這很有用。
禁用單獨測試用例
禁用子產品中單獨的測試用例，目前還不支援。 但是有一個變通方法， 将測試方法轉化為字元串，nightwatch 就會忽略它。
從 v0.5 開始， nightwatch 支援同時在多個環境中執行測試， 給 -e 參數指定多個值即可：
終端輸出
每個測試環境以一個子程序運作， 而輸出資訊會彙集到主程序。
為了使輸出資訊更易閱讀， nightwatch 預設會緩存所有輸出，在最後再以每個環境為一組，一起輸出這些資訊。
如果你想要禁止緩存輸出，在子程序的輸出發送到 stdout 後立即可見。需要在 nightwatch.json 檔案最外層(e.g selenium屬性之後) 中設定 live_output 屬性為true。
you can create a separate environment per browser (by chaining desiredcapabilities) and then run them in parallel. in addition, using the filter and exclude options tests can be split per environment in order to be ran in parallel.
via workers
從 v0.7 開始引入了一個新特性，