nightwatch配置

概览

自动生成配置

Nightwatch测试运行的二进制需要一个配置文件，默认情况下使用一个nightwatch.json从当前工作目录下的文件。若存在nightwatch.conf.js，则会先加载nightwatch.conf.js。
从1.3版本开始，基于操作系统和现有的驱动程序包，Nightwatch 将在根目录下默认生成一个配置文件nightwatch.conf.js。如果在当前文件夹中找到一个nightwatch.json或nightwatch.conf.js文件，则不会生成该文件。

手动配置

nightwatch.json

在项目根文件夹下创建nightwatch.json，假设您已经下载或安装了 ChromeDriver 服务，最简单的nightwatch.json文件将如下所示，其中node_modules/.bin/chromedriver是 ChromeDriver 的安装路径：

{
  "src_folders" : ["tests"],

  "webdriver" : {
    "start_process": true,
    "server_path": "node_modules/.bin/chromedriver",
    "port": 9515
  },

  "test_settings" : {
    "default" : {
      "desiredCapabilities": {
        "browserName": "chrome"
      }
    }
  }
}

nightwatch.conf.js

若存在nightwatch.conf.js则始终优先，如下为使用firefox作为目标浏览器的示例配置文件：

module.exports = {
  // 测试所在的文件夹数组
  src_folders: [],

webdriver: {
start_process: true,
port: 4444,
server_path: require('geckodriver').path,
cli_args: [
// very verbose geckodriver logs
// '-vv'
]
},

test_settings: {
default: {
launch_url: 'https://nightwatchjs.org',
desiredCapabilities : {
browserName : 'firefox',
alwaysMatch: {
// 如果会在firefox中遇到非预期的SSL验证问题，则需设置此项为true
// acceptInsecureCerts: true,
'moz:firefoxOptions': {
args: [
// '-headless',
// '-verbose'
],
}
}
}
}
}
};

默认配置

const filename_format = function ({testSuite = '', testCase = '', isError = false, dateObject = new Date()} = {}) {
  const fileName = [];
  const dateParts = dateObject.toString().replace(/:/g, '').split(' ');
  dateParts.shift();

  const dateStamp = dateParts.slice(0, 5).join('-');
  if (testSuite) {
    fileName.push(testSuite);
  }
  if (testCase) {
    fileName.push(testCase);
  }

  return ${fileName.join('/')}${isError ? '_ERROR' : '_FAILED'}_${dateStamp}.png;
};

module.exports = {
  // 加载自定义命令的位置
  custom_commands_path: null,

  // 加载自定义断言的位置
  custom_assertions_path: null,

  //  page object文件导入的位置
  page_objects_path: null,

  // 外部全局模块的位置，此模块会被导入到测试中作为client示例的全局属性
  globals_path: null,

  // 测试执行时，在主测试api中可用的对象
  globals: {

    // 控制测试执行在断言失败时是否中止并跳过其他断言，它被用于waitFor命令和expect断言
    abortOnAssertionFailure: true,

    // 控制当元素无法定位时是否终止测试执行；终止后一个错误被记录至所有用例中，且跳过剩下的所有用例。它被用于元素命令，如.click()、.getText()
    abortOnElementLocateError: false,

    //重写默认的重试间隔（500ms）， waitFor和expect 重试的间隔毫秒数
    waitForConditionPollInterval: 500,

    // waitFor等命令的默认超时时间
    waitForConditionTimeout: 5000,

    // 在多个元素都找到但未给定定位策略和选择器时，使waitFor命令抛出异常
    throwOnMultipleElementsReturned: false,

    // 默认情况下，如果使用给定的定位策略和选择器找到多个元素，则会打印警告； 将此设置为 true 以抑制这些警告
    suppressWarningsOnMultipleElementsReturned: false,

    // 控制异步挂钩的超时值。 期望在此时间内调用 done() 回调或抛出错误
    asyncHookTimeout: 10000,

    // 控制运行异步单元测试时的超时值。 期望在此时间内调用 done() 回调或抛出错误
    unitTestsTimeout: 2000,

    // 控制执行全局异步报告器时的超时值。 期望在此时间内调用 done() 回调或抛出错误
    customReporterCallbackTimeout: 20000,

    // 自动重试失败的断言直到达到给定的超时，然后放弃并失败测试。
    retryAssertionTimeout: 5000,

    reporter: function(results, cb) {cb(results)}
  },

  // dotenv 模块的配置设置 - 一个零依赖模块，将环境变量从 .env 文件加载到 process.env 中
  dotenv: {},

  // 在运行之间保留相同的全局对象，或者在每个测试中拥有它的（深层）副本； 
  // 当需要在测试套件之间保存数据时，这可能很有用，例如 cookie 或会话信息
  persist_globals: false,

  // JUnit XML 报告文件将被保存的位置。 如果要禁用 XML 报告，请将其设置为 false
  output_folder: 'tests_output',

  // 测试文件所在的字符串或文件夹数组（不包括子文件夹）。
  src_folders: null,

  // 在并行运行时使用，确定是否应在最后收集和显示输出
  live_output: false,

  // 禁用对加载打字稿文件的支持以向后兼容测试套件
  disable_typescript: false,

  // 用于禁用终端中的彩色输出
  disable_colors: false,

  // 用于并行运行时指定启动子进程之间的延迟（以毫秒为单位）
  parallel_process_delay: 10,

  // An object containing Selenium Server related configuration options
  selenium: {
    start_process: false,
    cli_args: {},
    server_path: null,
    log_path: '',
    port: undefined,
    check_process_delay: 500,
    max_status_poll_tries: 15,
    status_poll_interval: 200
  },

  // 是否自动启动 Selenium/WebDriver 会话。 如果运行单元测试，这应该设置为 false
  start_session: true,

  // 测试终止时自动结束会话，通常是在断言失败之后
  end_session_on_fail: true,

  // 当一个测试用例失败时，从当前测试用例中跳过剩余的测试用例
  skip_testcases_on_fail: undefined,

  // 是否并行运行单个测试文件
  test_workers: false,

  /
  test_workers: {
    enabled: true,

    // 根据 CPU 内核自动计算工作人员的数量
    workers: 'auto',

    // 手动指定工作人员的数量
    workers: 4,

    // 将节点参数传递给各个工作人员（所有 process.execArgv）
    node_options: 'auto',

    // 有选择地将节点参数传递给各个工作进程
    node_options: ['--inspect']
  },
  /

  // 指定使用哪个测试运行器: default|mocha
  test_runner: 'default',

  // 定义连接webdriver/selenium的选项
  webdriver: {
    start_process: false,
    cli_args: {},
    server_path: null,
    log_path: '',
    use_legacy_jsonwire: undefined,

    // 开始检查 Webdriver 服务器是否启动并运行之前的等待时间（以毫秒为单位）
    check_process_delay: 100,

    // 返回超时错误前的最大 ping 状态检查尝试次数
    max_status_poll_tries: 10,

    // 检查 Webdriver 服务器是否已启动并运行时， ping 检查之间使用的时间间隔（以毫秒为单位）
    status_poll_interval: 200,

    // 等待 Node.js 进程创建和运行的整个时间（以毫秒为单位）（默认为 2 分钟），包括生成子进程和检查状态
    process_create_timeout: 120000,
    host: undefined,
    port: undefined,
    ssl: undefined,
    proxy: undefined,
    timeout_options: {
      timeout: undefined,
      retry_attempts: undefined
    },
    default_path_prefix: undefined,
    username: undefined,
    access_key: undefined
  },

  test_settings: {
  },

  // 设置可以在稍后的测试中用作要加载的主 url
  launch_url: '',

  // 如果要显示来自 WebDriver 服务器的扩展 http 流量命令日志，请设置为 false
  silent: true,

  // 用于完全禁用终端输出
  output: true,

  // 如果您只想查看显示的测试用例名称和通过/失败状态，请将其设置为 false
  detailed_output: true,

  // 如果您想查看日志输出旁边的时间戳，请将其设置为 true
  output_timestamp: false,

  // 如果您希望将时间戳视为 ISO 字符串，请将其设置为 iso
  timestamp_format: '',

  // 如果您不想在测试执行期间显示错误（它们始终显示在末尾），请将其设置为 true。
  disable_error_log: false,

  // 默认情况下，不处理 DOM 元素（例如 cookie）的 API 命令错误会被忽略，除非它们是由 Node.js 抛出的（例如 ECONNRESET 错误）
  report_command_errors: false,

  // 在测试执行期间获取错误和失败截图
  screenshots: {
    enabled: false,
    filename_format,
    path: '',
    on_error: true,
    on_failure: true
  },

  // 用于在截屏时启用在（详细）日志中显示 Base64 图像数据
  log_screenshot_data: false,

  desiredCapabilities: {
    browserName: 'firefox'
  },

  // 要跳过的文件夹或文件模式数组（相对于主源文件夹）
  exclude: null,

  // 加载测试时使用的文件夹或文件模式。 与此模式不匹配的文件将被忽略
  filter: null,

  // 跳过一组测试（一个子文件夹）； 可以是逗号分隔值的列表（无空格）
  skipgroup: '',

  sync_test_names: true,

  // 按标签名称跳过测试； 可以是逗号分隔值的列表（无空格）
  skiptags: '',

  // 使用 xpath 作为默认定位器策略
  use_xpath: false,

  parallel_mode: false,

  report_prefix: '',

  unit_tests_mode: false,

  default_reporter: 'junit'
}

所有设置

基础设置

名称	类型	默认	描述
test_settings	object		一个对象，其中定义了所有测试环境，每个环境都根据需要覆盖测试设置。 始终需要默认环境，其他环境从中继承设置。
webdriver	object		webdriver相关配置
src_folders	string/array	none	测试所在的文件夹数组（不包括子文件夹）。如果未指定，则必须将测试源作为第二个参数内联传递给测试运行器
selenium	object		包含 Selenium Server 相关配置选项的对象。 如果不使用 Selenium，则应设置 webdriver 选项。从 Nightwatch 1.0 开始，只有在针对 Grid 设置或云测试服务（例如 SauceLabs 或 BrowserStack）进行测试时才需要 Selenium
custom_commands_path	string/array	none	加载自定义命令的位置
custom_assertions_path	string/array	none	加载自定义断言的位置
page_objects_path	string/array	none	加载页面对象文件的位置
globals_path	string/array	none	外部全局模块的位置，该模块将作为主客户端实例上的全局属性加载并可供测试使用。全局变量也可以在 test_settings 环境中定义/覆盖

Test Runner设置

设置用于控制内置 CLI 测试运行器的工作方式。

名称	类型	默认	描述
test_runner	string/object	“default”	指定运行测试时要使用的测试运行器。值可以是default(built-in nightwatch runner) 或mocha 。例子：“test_runner” : {“type” : “mocha”, “options” : {“ui” : “tdd”}}
parallel_process_delay	integer	10	指定以并行模式运行时启动子进程之间的延迟（以毫秒为单位）。
enable_fail_fast 从v1.2.2开始	boolean	false	当第一次测试失败发生时，启用中止测试运行执行；其余的测试套件将被跳过。
test_workers	boolean	false	是否为每个测试worker并行运行各个测试套件。如果设置为true，则并行运行测试并自动确定工作人员的数量。如果设置为一个对象，可以指定工人的数量为"auto"或 a number。例子：“test_workers” : {“enabled” : true, “workers” : “auto”}从 v1.3.7 开始，您可以使用该node_options属性指定要传递给各个测试工作进程的节点选项。示例：- 这将传递所有process.execArgv：- 这将仅传递指定的 cli 选项：“test_workers”: {“enabled”: true,“workers”: “auto”, “node_options”: “inherit”},“test_workers”: {“enabled”: true,“workers”: “auto”,“node_options”["–inspect"]},
unit_tests_mode	boolean	false	控制是否在单元测试模式下运行测试，这意味着不会自动创建会话。

Test Session设置

设置微调test session的行为并定义测试过程中可能可用的属性

设置baseUrl属性

baseUrl（或launchUrl）属性将提供测试中使用的主要 Nightwatch api。它的值取决于使用的环境。更多关于Nightwatch Runner的测试环境。
如果运行测试指定integration环境（使用--env integration），则baseUrl为http://staging.host。否则将设置为default中定义的值（即http://localhost）。

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

名称	类型	默认	描述
baseUrl	string	none	可以在稍后的测试中用作要加载的主 url 的 url。如果您的测试将在不同的环境中运行，每个环境都有不同的 url，这将很有用。别名：base_url, launch_url, launchUrl.
desiredCapabilities 别名: capabilities	object / function / Selenium Capabilities		何时创建新会话的 WebDriver 功能。如，您可以指定浏览器名称以及其他功能。
screenshots	object	none	当发生命令错误时，Selenium 会生成屏幕截图。随着on_failure设置为true，还产生了故障或示数的测试截图。这些都保存在磁盘上。如：“screenshots” : {“enabled” : true,“on_failure” : true,“on_error” : false,“path” : "”}
globals	object		在测试中可用并且可以在每个环境中覆盖的对象。示例：“globals” : { “myGlobal” : “some_global”}全局变量。也可以在外部文件中定义。关于外部全局变量。
start_session	boolean	true	是否自动启动 WebDriver 会话。通常在运行不与 Webdriver 服务器交互的单元/集成测试时设置为false。
end_session_on_fail	boolean	true	测试终止时自动结束会话，通常是在断言失败之后。
skip_testcases_on_fail	boolean	true	当一个测试用例失败时，跳过同一测试套件（即测试文件）中的剩余测试用例（或测试步骤）。
use_xpath	boolean	false	使用 xpath 作为默认定位器策略
use_ssl	boolean	false	如果通过 https 连接到远程 Grid 服务器，则设置为 true。同时设置port为 443。
sync_test_names	boolean	true	启用后name将向包含测试用例名称的desiredCapabilities属性中添加一个属性。在使用云测试服务时很有用
persist_globals	boolean	false	如果想在测试用例使用同一个全局对象则设置为true
selenium_host Deprecated - use selenium.host	string	localhost	Selenium 服务器接受连接的主机名/IP。
selenium_port Deprecated - use selenium.port	integer	4444	Selenium 服务器接受连接的端口号。

过滤设置

用于定义过滤测试文件的方式

名称	类型	默认	描述
exclude	array		要跳过的文件夹或文件模式数组（相对于主源文件夹）。示例："exclude" : ["excluded-folder"]或："exclude" : ["test-folder/*-smoke.js"]
filter	string		加载测试时使用的文件夹或文件模式。与此模式不匹配的文件将被忽略。例子："filter" : "tests/*-smoke.js"
skipgroup	string		跳过一组测试（一个子文件夹）；可以是逗号分隔值的列表（无空格）。
skiptags	string		按标签名称跳过测试；可以是逗号分隔值的列表（无空格）。

输出设置

用于设置允许测试控制输出和日志记录

名称	类型	默认	描述
output_folder	string	tests_output	JUnit XML 报告文件将被保存的位置。
disable_colors	boolean	false	控制是否全局禁用 CLI 输出的着色。
live_output	boolean	false	此选项仅在并行运行测试时有用。控制是否缓冲输出。
silent	boolean	true	是否显示来自 WebDriver 或 Selenium 服务器的扩展 HTTP 流量命令日志。
output	boolean	true	用于完全禁用 CLI 输出。
detailed_output	boolean	true	默认情况下，在测试运行时会显示详细的断言输出。false如果您只想查看显示的测试用例名称和通过/失败状态，请将其设置为。并行运行测试时，默认情况下禁用详细输出。
disable_error_log	boolean	false	如果您不想在测试执行期间显示错误（它们始终显示在末尾），请将其设置为 true。
output_timestamp	boolean	false	如果您想查看日志输出旁边的时间戳，请将其设置为 true。
log_screenshot_data	boolean	false	用于在截屏时启用在（详细）日志中显示 Base64 图像数据。

Webdriver 设置

以下是 Webdriver 服务的一些选项。Nightwatch 可以自动启动和停止 Webdriver 进程。如果想启用此功能，设置start_process到true并指定二进制文件中的位置server_path。

名称	类型	默认	描述
start_process	boolean	false	启用此选项后，Webdriver 服务器将在子进程的后台运行并自动启动/停止。Nightwatch 支持管理 Chromedriver、Geckodriver (Firefox)、Safaridriver 和 Selenium Server。有关详细信息，请参阅安装 Webdriver部分。
server_path	string	none	仅在start_process启用时有用。
host	string		仅当 Webdriver 服务在不同的机器上运行时才需要。
port	integer		Webdriver监听 或 Nightwatch 将尝试连接的端口号
ssl	boolean		如果true通过 HTTPS 连接到远程（云）服务，则应设置为。也不要忘记将端口设置为 443。
log_path	string/boolean	none	output.log将放置Webdriver 服务日志文件文件的位置。默认为当前目录。要禁用 Webdriver 日志记录，请将其设置为false
log_file_name	string/none	none	默认情况下，日志文件名将与测试用例文件名相同，但也可以指定不同的文件名。
cli_args	object	none	要传递给 Webdriver 进程的 cli 参数列表。这因每个 Webdriver 实现而异。
keep_alive	boolean/object	false	启用HTTP Keep-Alive。如果设置为truekeepAlive 选项，则使用默认设置 ( keepAliveMsecs= 3000)启用。如果设置为对象，可以指定指定keepAliveMsecs值。如：“keep_alive” : {“enabled” : true, “keepAliveMsecs” : 2000}
timeout_options	object	timeout: 60000, retry_attempts: 0	对 Webdriver 服务的请求将以timeout毫秒为单位超时；重试将发生retry_attempts多次。如：{timeout: 15000, retry_attempts: 5}
status_poll_interval	integer	100	检查 Webdriver 服务器是否已启动并运行时，状态 ping 检查之间使用的时间间隔（以毫秒为单位）
max_status_poll_tries	integer	5	在返回超时错误之前检查 Webdriver 服务器是否已启动并运行时尝试 ping 状态检查的最大次数。
process_create_timeout	integer	120000	等待 Node.js 进程创建和运行的整个时间（以毫秒为单位）（默认为 2 分钟），包括生成子进程和检查状态
username	string	none	通常只需要云测试 Selenium 服务。如果服务器需要凭据，则此用户名将用于计算Authorization标头。该值也可以是环境变量：“username” : “${SAUCE_USERNAME}”
access_key	string	none	该字段将与username计算Authorization标题一起使用。该值也可以是环境变量：“access_key” :"${SAUCE_ACCESS_KEY}"
proxy	string	none	对 Webdriver（或 Selenium）服务的代理请求。接受 http、https、socks(v5)、socks5、sock4 和 pac。使用需要作为独立于 NPM 的单独包安装的代理代理。
default_path_prefix	string		有时在使用 Selenium 服务器时需要。添加到所有请求的前缀（例如/wd/hub）。

Selenium设置

如果使用 Selenium Server，那么连接相关的设置应该放在"selenium"". 如果webdriver和selenium都存在，则selenium配置项会与webdriver配置项合并。
"selenium"在配置与基于云的测试提供程序的连接时，也应使用这些设置，例如BrowserStack、SauceLabs、CrossBrowserTesting或LambdaTest。

名称	类型	默认	描述
start_process	boolean	false	是否自动管理 Selenium 进程。
server_path	string	none	Selenium.jar文件的位置。如果start_process启用，则需要指定此项。例如：bin/selenium-server-standalone-2.43.0.jar
log_path	string/boolean	none	Seleniumoutput.log文件存放位置。默认为当前目录。要禁用 Selenium 日志则设置为false
version2	boolean	false	如果使用的是Selenium Server 2，则设置为true
port	integer	4444	Selenium 监听或 Nightwatch 尝试连接的端口号。
cli_args	object	none	要传递给 Selenium 进程的 cli 参数列表。您可以在此处为浏览器驱动程序设置各种选项。

Selenium 示例配置

nightwatch.conf.js示例配置，它使用支持 Firefox、Chrome 和 Internet Explorer 的本地 Selenium 服务器。假设下列npm包已安装在当前项目中：geckodriver、chromedriver、selenium-server、iedriver

module.exports = {
  src_folders: [],

  test_settings: {
    default: {
    launch_url: 'https://nightwatchjs.org'
  },

  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: {
        //默认情况下，Selenium 将为每个会话创建一个新的 Firefox 配置文件。
        'webdriver.gecko.driver': require('geckodriver').path,
        //Nightwatch 也可以使用Chrome浏览器运行测试。
        //要启用此功能，您必须下载ChromeDriver驱动程序并在此处指定其位置,将 chrome 指定为desiredCapabilities对象中的浏览器名称。
        //更多信息可以在ChromeDriver 网站上找到。
        'webdriver.chrome.driver': require('chromedriver').path,
        //Nightwatch 也适用于Internet Explorer。要启用此功能，您必须下载IE驱动程序并在此处指定它的位置。
        'webdriver.ie.driver': process.platform === 'win32' ? require('iedriver').path : ''
      }
    },
    webdriver: {
      start_process: false
    }
  },

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

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

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

BrowserStack 示例配置

Browserstack是最流行的云测试平台之一。将它与 Nightwatch 一起使用非常简单，并且在自动生成的nightwatch.conf.js文件中有配置。拥有帐户后，您需要设置以下环境变量BROWSERSTACK_USER，BROWSERSTACK_KEY。Nightwatch也支持Dotenv文件。

module.exports = {
  src_folders: [],

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

  test_settings: {
    default: {
      launch_url: 'https://nightwatchjs.org'
    },

    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 : {
          w3c: false
        }
      }
    },

    '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'
        }
      }
    }
  }
}