Nightwatch 設定 | 開發者指南 | Nightwatch.js 測試框架

基本設定

以下是在測試執行期間將傳遞至 Nightwatch 實例的預設設定。

名稱	類型	預設值	描述
`src_folders`	字串 \| 陣列 \| `glob 樣式`	無	測試所在的資料夾 (不包括子資料夾) 陣列。如果未指定此項，則必須將測試來源內嵌傳遞為測試執行器的第二個引數。
`test_settings`	物件		在其中定義所有測試環境的物件，每個環境都會根據需要覆寫測試設定。始終需要一個 `default` 環境，其他環境會從中繼承設定。有關詳細資訊，請參閱定義測試環境。
`webdriver`	物件		一個包含與 WebDriver 相關的組態選項的物件。
`selenium`	物件		一個包含與 Selenium Server 相關的組態選項的物件。如果未使用 Selenium Server，則應改為設定 `webdriver` 選項。從 Nightwatch 1.0 開始，只有在針對網格設定或雲端測試服務 (例如 SauceLabs 或 BrowserStack) 進行測試時，才需要 Selenium。
`custom_commands_path`	字串 \| 陣列 \| `glob 樣式`	無	將從中載入自訂命令的位置。
`custom_assertions_path`	字串 \| 陣列 \| `glob 樣式`	無	將從中載入自訂斷言的位置。
`page_objects_path`	字串 \| 陣列 \| `glob 樣式`	無	將從中載入頁面對象檔案的位置。
`globals_path`	字串	無	外部全域模組的位置，該模組將被載入並作為主要客戶端實例上的屬性 `globals` 提供給測試。全域變數也可以在 `test_settings` 環境內定義/覆寫。
`backwards_compatibility_mode` 自 v2.0 起	布林值	false	在 Nightwatch v1.x 中，當與 `await` 運算子搭配使用時，API 命令將返回完整的結果物件，格式為 {value: `<VALUE>`}，而在 v2 中，則直接返回該值。如果使用回呼，則行為保持不變。
`disable_global_apis` 自 v2.0 起	布林值	false	停用全域 API，例如 `"browser"`、`"element()"`、`"expect()"`；如果將 Nightwatch 與協力廠商程式庫搭配使用，則可能需要此項。

測試執行器設定

以下設定用於控制內建 CLI 測試執行器的工作方式。

名稱	類型	預設值	描述
`test_runner`	字串 \| 物件	"default"	指定執行測試時要使用的測試執行器。值可以是 `default` (內建 Nightwatch 執行器) 或 `mocha`。範例：`"test_runner" : {"type" : "mocha", "options" : {"ui" : "tdd"}}`
`parallel_process_delay`	整數	10	指定在並行模式下執行時啟動子處理序之間的延遲 (以毫秒為單位)。
`enable_fail_fast` 自 v2.0 起	布林值	false	啟用在發生第一個測試失敗時中止測試執行；將跳過其餘的測試套件。
`test_workers`	布林值 \| 物件	false	是否使用測試工作者 (每個工作者一個) 並行執行個別的測試套件。如果設定為 `true`，則並行執行測試並自動判斷工作者的數量。如果設定為物件，則可以將工作者的數量指定為 `"auto"` 或 `number`。範例：`"test_workers" : {"enabled" : true, "workers" : "auto"}` 從 v1.3.7 開始，您可以使用 `node_options` 屬性指定要傳遞給個別測試工作者處理序的節點選項。範例 - 這將傳遞所有 `process.execArgv` `"test_workers": { "enabled": true, "workers": "auto", "node_options": "inherit" },` - 這將只傳遞指定的 cli 選項 `"test_workers": { "enabled": true, "workers": "auto", "node_options": ["--inspect"] },`
`unit_tests_mode`	布林值	false	控制是否在單元測試模式下執行測試，這表示不會自動建立 Session。

測試 Session 設定

這些設定用於微調測試 Session 的行為，並定義在 Session 過程中可能可用的屬性。

設定 `baseUrl` 屬性

這個 baseUrl (或 launchUrl) 屬性將提供給測試中使用的主要 Nightwatch API。其值取決於使用的環境。如需更多測試環境資訊，請參閱 Nightwatch 執行器章節。

如果您執行測試時指定 integration 環境 (使用 --env integration)，則根據組態，baseUrl 將設定為 http://staging.host。否則，其值將為 default 環境中定義的值 (即 https://127.0.0.1)。

module.exports = {
  'Demo test' : function (browser) {
    browser
      .url(browser.baseUrl)
      // ...
      .end();
  }
};

名稱	類型	預設值	描述
`baseUrl`	字串	無	一個 URL，稍後可以在測試中用作載入的主要 URL。如果您的測試將在不同的環境中執行，每個環境都有不同的 URL，則此屬性會很有用。別名：`base_url`、`launch_url`、`launchUrl`。
`desiredCapabilities` 別名：`capabilities`	物件 \| 函式 \| Selenium 功能		建立新 Session 時的 WebDriver 功能。您可以指定瀏覽器名稱以及其他功能。範例 `"desiredCapabilities" : { "browserName" : "firefox", "acceptInsecureCerts" : true }` 您可以在這裡檢視完整的功能清單。自 v2.0 起，也可以指定 Selenium 功能物件。範例 `const firefox = require('selenium-webdriver/firefox'); const options = new firefox.Options() .addExtensions('../../../path/to/extension.xpi'); module.exports = { src_folders: ['tests'], test_settings: { default: { browserName: 'firefox', desiredCapabilities: options } } };` 或作為函式 `module.exports = { src_folders: ['tests'], test_settings: { default: { browserName: 'firefox', desiredCapabilities() { const firefox = require('selenium-webdriver/firefox'); const options = new firefox.Options() .addExtensions('../../../path/to/extension.xpi'); return options; } } } };`
`screenshots`	物件	無	當發生命令錯誤時，Selenium 會產生螢幕快照。如果 `on_failure` 設定為 true，也會為失敗或出錯的測試產生螢幕快照。這些螢幕快照會儲存在磁碟上。自 `v0.7.5` 起，您可以將 `"on_error"` 設定為 `false`，來停用命令錯誤的螢幕快照。範例 `"screenshots" : { "enabled" : true, "on_failure" : true, "on_error" : false, "path" : "" }`
`globals`	物件		一個將在測試中提供的物件，並且可以在每個環境中覆寫。範例 `"globals" : { "myGlobal" : "some_global" }` 全域變數也可以在外部檔案中定義。如需更多資訊，請參閱外部全域變數。
`persist_globals`	布林值	false	如果您希望在測試套件執行之間保留相同的全域物件，或讓每個測試套件都擁有其 (深層) 複本，則請將此項設定為 `true`。
`start_session`	布林值	true	是否自動啟動 WebDriver Session。當執行不與 Webdriver 伺服器互動的單元/整合測試時，通常會將此項設定為 `false`。
`end_session_on_fail`	布林值	true	當測試終止時自動結束 Session，通常是在斷言失敗後。
`skip_testcases_on_fail`	布林值	true	當一個測試案例失敗時，跳過同一個測試套件 (即測試檔案) 中的其餘測試案例 (或測試步驟)。
`use_xpath`	布林值	false	使用 xpath 作為預設的定位器策略
`use_ssl`	布林值	false	如果透過 https 連線至遠端網格伺服器，請設定為 true。此外，別忘了將 `port` 設定為 443。
`sync_test_names`	布林值	true	啟用此功能時，將在 `desiredCapabilities` 中新增一個 `name` 屬性，其中包含測試套件名稱。在使用雲端測試服務時，這很有用。
`persist_globals`	布林值	false	如果您希望在測試套件執行之間保留相同的全域物件，或讓每個測試套件都擁有其 (深層) 複本，則請將此項設定為 `true`。
`selenium_host` 已棄用 - 使用 `selenium.host`	字串	localhost	Selenium Server 接受連線的主機名稱/IP。
`selenium_port` 已棄用 - 使用 `selenium.port`	整數	4444	Selenium Server 接受連線的連接埠號碼。

篩選設定

以下設定可用於定義篩選測試檔案的方式。

名稱	類型	描述
`exclude`	陣列	要略過的資料夾或檔案樣式陣列 (相對於主要來源資料夾)。範例 `"exclude" : ["excluded-folder"]` 或 `"exclude" : ["test-folder/\*-smoke.js"]`
`filter`	字串	載入測試時使用的資料夾或檔案模式。不符合此模式的檔案將會被忽略。範例 `"filter" : "tests/\*-smoke.js"`
`skipgroup`	字串	略過一組測試 (一個子資料夾)；可以是逗號分隔的值列表 (無空格)。
`skiptags`	字串	依標籤名稱略過測試；可以是逗號分隔的值列表 (無空格)。

輸出設定

以下設定可用於控制執行測試時的輸出和記錄。

名稱	類型	預設值	描述
`output_folder`	字串	tests_output	JUnit XML 報告檔案將儲存的位置。
`disable_colors`	布林值	false	控制是否全域停用 CLI 輸出的色彩。
`live_output`	布林值	false	此選項僅在並行執行測試時有用。控制是否要緩衝輸出。
`silent`	布林值	true	是否顯示來自 WebDriver 或 Selenium 伺服器的擴展 HTTP 流量命令日誌。
`output`	布林值	true	用於完全停用 CLI 輸出。
`detailed_output`	布林值	true	預設情況下，在測試執行時會顯示詳細的斷言輸出。如果您只想看到顯示的測試案例名稱和通過/失敗狀態，請將其設定為 `false`。在並行執行測試時，預設會停用詳細輸出。
`disable_error_log`	布林值	false	如果您不想在測試執行期間顯示錯誤 (它們始終會在最後顯示)，請將其設定為 true。
`output_timestamp`	布林值	false	如果您想在記錄輸出旁邊看到時間戳記，請將其設定為 true。
`log_screenshot_data`	布林值	false	用於啟用在擷取螢幕截圖時在 (詳細) 日誌中顯示 Base64 影像資料。

WebDriver 設定

以下是 Webdriver 服務的一些選項。Nightwatch 可以自動啟動和停止 Webdriver 程序，這非常方便，因為您不必自己管理它，只需專注於測試。

如果您想啟用此功能，請將 start_process 設定為 true，並在 server_path 內指定二進位檔案的位置。

名稱	類型	預設值	描述
`start_process`	布林值	false	啟用此選項後，Webdriver 伺服器會在子程序中於背景執行，並自動啟動/停止。 Nightwatch 包含對管理 Chromedriver、Geckodriver (Firefox)、Safaridriver 和 Selenium Server 的支援。
`server_path`	字串	無	僅在啟用 `start_process` 時有用。
`host`	字串		僅當 Webdriver 服務在不同的機器上執行時才需要。
`port`	整數		Webdriver 服務將監聽或 Nightwatch 將嘗試連線的連接埠號碼。
`ssl`	布林值		如果透過 HTTPS 連線至遠端 (雲端) 服務，則應設定為 `true`。也別忘了將連接埠設定為 443。
`log_path`	字串\|布林值	無	Webdriver 服務記錄檔 `output.log` 檔案將放置的位置。預設為目前目錄。若要停用 Webdriver 記錄，請將此設定為 `false`
`log_file_name`	字串\|無	無	預設情況下，記錄檔名稱將與測試套件檔案名稱相同，但也可以指定不同的檔案名稱。
`cli_args`	物件	無	要傳遞至 Webdriver 程序的 cli 引數清單。這會因每個 Webdriver 實作而異。
`keep_alive`	布林值 \| 物件	false	啟用 HTTP Keep-Alive。如果設定為 `true`，則會以預設設定啟用 keepAlive 選項 (`keepAliveMsecs` = 3000)。如果設定為物件，則可以指定 `keepAliveMsecs` 值。範例：`"keep_alive" : {"enabled" : true, "keepAliveMsecs" : 2000}`
`timeout_options`	物件	timeout: 60000 retry_attempts: 0	對 Webdriver 服務的要求將在 `timeout` 毫秒後逾時；將會重試 `retry_attempts` 次。範例 `{timeout: 15000, retry_attempts: 5}`
`status_poll_interval` 自 v1.2.2 起	整數	100	在檢查 Webdriver 伺服器是否已啟動並執行時，用於狀態 ping 檢查之間的間隔 (以毫秒為單位)
`max_status_poll_tries` 自 v1.2.2 起	整數	5	在檢查 Webdriver 伺服器是否已啟動並執行時，傳回逾時錯誤之前，最大 ping 狀態檢查嘗試次數。
`process_create_timeout` 自 v1.2.2 起	整數	120000	等待 Node.js 程序建立並執行的總時間 (以毫秒為單位) (預設為 2 分鐘)，包括產生子程序和檢查狀態
`username`	字串	無	通常僅適用於雲端測試 Selenium 服務。如果伺服器需要認證，則此使用者名稱將用於計算 `Authorization` 標頭。該值也可以是環境變數，在這種情況下，它看起來像這樣 `"username" : "${SAUCE_USERNAME}"`
`access_key`	字串	無	此欄位將與 `username` 一起用於計算 `Authorization` 標頭。與 `username` 一樣，該值也可以是環境變數 `"access_key" : "${SAUCE_ACCESS_KEY}"`
`proxy`	字串	無	Proxy 對 Webdriver (或 Selenium) 服務的要求。接受 http、https、socks(v5)、socks5、sock4 和 pac。使用 proxy-agent，需要從 NPM 安裝為個別套件。範例：`http://user:pass@host:port`
`default_path_prefix`	字串		有時在使用 Selenium Server 時需要。要新增至所有要求的字首 (例如 /wd/hub)。

Selenium Server 設定

如果正在使用 Selenium Server，則連線相關設定應放置在 "selenium" 下。如果同時存在 webdriver 和 selenium 字典，則會將 selenium 選項與 webdriver 選項合併。

在設定與雲端測試提供者 (例如 BrowserStack、SauceLabs、CrossBrowserTesting、LambdaTest 或 TestingBot) 的連線時，也應使用 "selenium" 設定。

名稱	類型	預設值	描述
`start_process`	布林值	false	是否要自動管理 Selenium 程序。
`server_path`	字串	無	Selenium `jar` 檔案的位置。如果啟用 `start_process`，則必須指定此選項。例如：`bin/selenium-server-standalone-2.43.0.jar`
`log_path`	字串\|布林值	無	Selenium `output.log` 檔案將放置的位置。預設為目前目錄。若要停用 Selenium 記錄，請將此設定為 `false`
`version2`	布林值	false	如果您需要使用舊版 Selenium Server 2，請將此設定為 `true`。
`port`	整數	4444	Selenium 將監聽或 Nighwatch 將嘗試連線的連接埠號碼。
`cli_args`	物件	無	要傳遞至 Selenium 程序的 cli 引數清單。您可以在此處設定瀏覽器驅動程式的各種選項，例如 `webdriver.firefox.profile`：Selenium 預設會為每個工作階段建立新的 Firefox 設定檔。如果您希望使用現有的 Firefox 設定檔，您可以在此處指定其名稱。可用的完整 Firefox Driver 引數清單位於此處。 `webdriver.chrome.driver`：Nightwatch 也可以使用 Chrome 瀏覽器執行測試。若要啟用此功能，您必須下載 ChromeDriver 二進位檔，並在此處指定其位置。也別忘了在 `desiredCapabilities` 物件中將 chrome 指定為瀏覽器名稱。如需詳細資訊，請參閱 ChromeDriver 網站。 `webdriver.ie.driver`：Nightwatch 也適用於 Internet Explorer。若要啟用此功能，您必須下載 IE Driver 二進位檔，並在此處指定其位置。或者，您可以從 NPM 安裝套件 `iedriver`。此外，您需要在 `desiredCapabilities` 物件中將「internet explorer」指定為瀏覽器名稱。

Selenium 範例設定

以下是在 nightwatch.conf.js 中作為一部分的範例設定，其使用本機 Selenium Server 支援 Firefox、Chrome 和 Internet Explorer。

假設下列 NPM 套件已安裝在目前專案中

module.exports = {
  src_folders: [],
  

  test_settings: {
    default: {
    launch_url: 'https://nightwatch.dev.org.tw'
  },
  

  selenium: {
    // Selenium Server is running locally and is managed by Nightwatch
    selenium: {
      start_process: true,
      port: 4444,
      server_path: require('selenium-server').path,
      cli_args: {
        'webdriver.gecko.driver': require('geckodriver').path,
        'webdriver.chrome.driver': require('chromedriver').path,
        'webdriver.ie.driver': process.platform === 'win32' ? require('iedriver').path : ''
      }
    },
    webdriver: {
      start_process: false
    }
  },
  

  'selenium.chrome': {
    extends: 'selenium',
    desiredCapabilities: {
      browserName: 'chrome',
      chromeOptions: {
      }
    }
  },
  

  'selenium.firefox': {
    extends: 'selenium',
    desiredCapabilities: {
      browserName: 'firefox'
    }
  },
  

  'selenium.ie': {
    extends: 'selenium',
    desiredCapabilities: {
      browserName: 'internet explorer'
    }
  }
}
}

BrowserStack 範例設定

Browserstack 是最熱門的雲端測試平台之一。將其與 Nightwatch 一起使用非常簡單，並且在自動產生的 nightwatch.conf.js 檔案中有設定。

擁有帳戶後，您需要設定下列環境變數。Nightwatch 也支援 Dotenv 檔案。

BROWSERSTACK_USER
BROWSERSTACK_KEY

請記住，也要啟用 HTTP keepalive 以改善網路效能。

module.exports = {
  src_folders: [],
  

  webdriver: {
    keep_alive: true,
    timeout_options: {
      timeout: 60000,
      retry_attempts: 3
    }
  }
  

  test_settings: {
    default: {
      launch_url: 'https://nightwatch.dev.org.tw'
    },
    

    browserstack: {
      selenium: {
        host: 'hub-cloud.browserstack.com',
        port: 443
      },
      

      // More info on configuring capabilities can be found on:
      // https://www.browserstack.com/automate/capabilities?tag=selenium-4
      desiredCapabilities: {
        'bstack:options' : {
          local: 'false',
          userName: '${BROWSERSTACK_USER}',
          accessKey: '${BROWSERSTACK_KEY}',
        }
      }
    },
    

    'browserstack.chrome': {
      extends: 'browserstack',
      desiredCapabilities: {
        browserName: 'chrome',
        chromeOptions : {
        }
      }
    },
    

    'browserstack.firefox': {
      extends: 'browserstack',
      desiredCapabilities: {
        browserName: 'firefox'
      }
    },
    

    'browserstack.ie': {
      extends: 'browserstack',
      desiredCapabilities: {
        browserName: 'IE',
        browserVersion: '11.0',
        'bstack:options' : {
          os: 'Windows',
          osVersion: '10',
          local: 'false',
          seleniumVersion: '3.5.2',
          resolution: '1366x768'
        }
      }
    }
  }
}