跳到主要內容

設定

根據設定類型（例如，使用原始協定綁定、WebdriverIO 作為獨立套件或 WDIO 測試執行器），可以使用不同的選項集來控制環境。

WebDriver 選項​

使用 webdriver 協定套件時，會定義以下選項

協定​

與驅動程式伺服器通訊時要使用的協定。

類型：String
預設值：http

hostname​

驅動程式伺服器的主機。

類型：String
預設值：0.0.0.0

port​

驅動程式伺服器所在的連接埠。

類型：Number
預設值：undefined

path​

驅動程式伺服器端點的路徑。

類型：String
預設值：/

queryParams​

傳播到驅動程式伺服器的查詢參數。

類型：Object
預設值：undefined

user​

您的雲端服務使用者名稱（僅適用於 Sauce Labs、Browserstack、TestingBot 或 LambdaTest 帳戶）。如果設定，WebdriverIO 會自動為您設定連線選項。如果您不使用雲端提供者，則可以使用此選項來驗證任何其他 WebDriver 後端。

類型：String
預設值：undefined

key​

您的雲端服務存取金鑰或密鑰（僅適用於 Sauce Labs、Browserstack、TestingBot 或 LambdaTest 帳戶）。如果設定，WebdriverIO 會自動為您設定連線選項。如果您不使用雲端提供者，則可以使用此選項來驗證任何其他 WebDriver 後端。

類型：String
預設值：undefined

capabilities​

定義您要在 WebDriver 會話中執行的功能。請查看 WebDriver 協定以了解更多詳細資訊。如果您執行不支援 WebDriver 協定的舊版驅動程式，則需要使用 JSONWireProtocol 功能才能成功執行會話。

除了基於 WebDriver 的功能之外，您還可以應用瀏覽器和供應商特定的選項，以便對遠端瀏覽器或裝置進行更深入的設定。這些會在相應的供應商文件中記錄，例如：

此外，一個有用的工具是 Sauce Labs 自動化測試組態器，它可以協助您按一下滑鼠來建立所需功能的物件。

類型：Object
預設值：null

範例

{
    browserName: 'chrome', // options: `chrome`, `edge`, `firefox`, `safari`
    browserVersion: '27.0', // browser version
    platformName: 'Windows 10' // OS platform
}

如果您在行動裝置上執行 Web 或原生測試，則 capabilities 與 WebDriver 協定不同。請參閱 Appium 文件以了解更多詳細資訊。

logLevel​

記錄詳細程度的等級。

類型：String
預設值：info
選項：trace | debug | info | warn | error | silent

outputDir​

儲存所有測試執行器記錄檔的目錄（包括報表工具記錄和 wdio 記錄）。如果未設定，所有記錄都會串流至 stdout。由於大多數報表工具都是用來記錄到 stdout，因此建議僅針對特定報表工具使用此選項，因為將報表推送至檔案會更有意義（例如 junit 報表工具）。

在獨立模式下執行時，WebdriverIO 產生的唯一記錄將會是 wdio 記錄。

類型：String
預設值：null

connectionRetryTimeout​

對驅動程式或網格的任何 WebDriver 請求逾時。

類型：Number
預設值：120000

connectionRetryCount​

對 Selenium 伺服器的最大請求重試次數。

類型：Number
預設值：3

agent​

允許您使用自訂 http/https/http2 代理 來發出請求。

類型：Object
預設值

{
    http: new http.Agent({ keepAlive: true }),
    https: new https.Agent({ keepAlive: true })
}

headers​

指定要傳遞到每個 WebDriver 請求的自訂 headers。如果您的 Selenium Grid 需要基本驗證，我們建議通過此選項傳遞 Authorization 標頭，以驗證您的 WebDriver 請求，例如：

import { Buffer } from 'buffer';
// Read the username and password from environment variables
const username = process.env.SELENIUM_GRID_USERNAME;
const password = process.env.SELENIUM_GRID_PASSWORD;

// Combine the username and password with a colon separator
const credentials = `${username}:${password}`;
// Encode the credentials using Base64
const encodedCredentials = Buffer.from(credentials).toString('base64');

export const config: WebdriverIO.Config = {
    // ...
    headers: {
        Authorization: `Basic ${encodedCredentials}`
    }
    // ...
}

類型：Object
預設值：{}

transformRequest​

在發出 WebDriver 請求之前攔截 HTTP 請求選項的函式

類型：(RequestOptions) => RequestOptions
預設值：無

transformResponse​

在收到 WebDriver 回應後攔截 HTTP 回應物件的函式。該函式會將原始回應物件作為第一個引數，並將對應的 RequestOptions 作為第二個引數傳遞。

類型：(Response, RequestOptions) => Response
預設值：無

strictSSL​

是否不需要 SSL 憑證有效。可以通過環境變數設定為 STRICT_SSL 或 strict_ssl。

類型：Boolean
預設值：true

enableDirectConnect​

是否啟用 Appium 直接連線功能。如果回應在啟用旗標時沒有適當的密鑰，則不會執行任何操作。

類型：Boolean
預設值：true

cacheDir​

快取目錄根目錄的路徑。此目錄用於儲存嘗試啟動會話時下載的所有驅動程式。

類型：String
預設值：process.env.WEBDRIVER_CACHE_DIR || os.tmpdir()

WebdriverIO​

以下選項（包括上面列出的選項）可以與獨立的 WebdriverIO 搭配使用

automationProtocol​

已棄用

WebdriverIO 正在棄用通過類似 WebDriver 的介面使用 Chrome Devtools 作為自動化協定。相反，您應該使用 webdriver。

定義您要用於瀏覽器自動化的協定。目前僅支援 webdriver 和 devtools，因為這些是可用的主要瀏覽器自動化技術。

如果您想使用 devtools 自動化瀏覽器，請確保您已安裝 NPM 套件 ($ npm install --save-dev devtools)。

類型：String
預設值：webdriver

baseUrl​

通過設定基本 URL 來縮短 url 命令呼叫。

  • 如果您的 url 參數以 / 開頭，則會將 baseUrl 添加到前面（但會排除 baseUrl 本身的路徑，如果有的話）。
  • 如果您的 url 參數開頭沒有 scheme 或 /（例如 some/path），則會直接將完整的 baseUrl 添加到前面。

類型：String
預設值：null

waitforTimeout​

所有 waitFor* 命令的預設逾時時間。（請注意選項名稱中的小寫 f。）此逾時時間僅影響以 waitFor* 開頭的命令及其預設等待時間。

若要增加測試的逾時時間，請參閱框架文件。

類型：Number
預設值：5000

waitforInterval​

所有 waitFor* 命令檢查預期狀態（例如可見性）是否已變更的預設間隔時間。

類型：Number
預設值：500

region​

如果在 Sauce Labs 上執行，您可以選擇在不同的資料中心（美國或歐洲）之間執行測試。若要將您的區域變更為歐洲，請在您的組態中加入 region: 'eu'。

注意：只有在您提供連接到您的 Sauce Labs 帳戶的 user 和 key 選項時，此設定才會生效。

類型：String
預設值：us

（僅適用於 vm 和或 em/模擬器）

Testrunner 選項​

以下選項（包括上面列出的選項）僅針對使用 WDIO testrunner 執行 WebdriverIO 時定義。

specs​

定義測試執行的規格。您可以指定一個 glob 模式來一次比對多個檔案，或將一個 glob 或一組路徑包裝到一個陣列中，以便在單一工作程序中執行它們。所有路徑均視為相對於組態檔案路徑。

類型：(String | String[])[]
預設值：[]

exclude​

從測試執行中排除規格。所有路徑均視為相對於組態檔案路徑。

類型：String[]
預設值：[]

suites​

一個描述各種套件的物件，然後您可以使用 wdio CLI 上的 --suite 選項指定這些套件。

類型：Object
預設值：{}

capabilities​

與上面描述的 capabilities 區段相同，但可選擇指定 multiremote 物件，或在陣列中指定多個 WebDriver 會話以進行平行執行。

您可以套用與 上面定義的相同的供應商和瀏覽器特定功能。

類型：Object|Object[]
預設值：[{ maxInstances: 5, browserName: 'firefox' }]

maxInstances​

平行執行的工作程序的總數上限。

注意：當測試在 Sauce Labs 等外部供應商的機器上執行時，此數字可能會高達 100。在這種情況下，測試不是在單一機器上進行，而是在多個 VM 上進行。如果要在本機開發機器上執行測試，請使用更合理的數字，例如 3、4 或 5。基本上，這是同時啟動並執行您的測試的瀏覽器數量，因此取決於您的機器上有多少 RAM，以及您的機器上執行了多少其他應用程式。

類型：Number
預設值：100

maxInstancesPerCapability​

每個功能平行執行工作程序的總數上限。

類型：Number
預設值：100

injectGlobals​

將 WebdriverIO 的全域變數（例如 browser、$ 和 $$）插入到全域環境中。如果您將其設定為 false，則應從 @wdio/globals 匯入，例如：

import { browser, $, $$, expect } from '@wdio/globals'

注意：WebdriverIO 不會處理測試框架特定全域變數的注入。

類型：Boolean
預設值：true

bail​

如果您希望測試執行在特定數量的測試失敗後停止，請使用 bail。（預設值為 0，表示無論如何都會執行所有測試。）注意：此處的測試是指單一規格檔案中的所有測試（當使用 Mocha 或 Jasmine 時），或功能檔案中的所有步驟（當使用 Cucumber 時）。如果您想要控制單一測試檔案中測試的 bail 行為，請查看可用的 framework 選項。

類型：Number
預設值：0（不 bail；執行所有測試）

specFileRetries​

整個規格檔案失敗時要重試的次數。

類型：Number
預設值：0

specFileRetriesDelay​

規格檔案重試嘗試之間以秒為單位的延遲時間

類型：Number
預設值：0

specFileRetriesDeferred​

是否應立即重試重試的規格檔案，還是將其延遲到佇列末尾。

類型：Boolean
預設值：true

groupLogsByTestSpec​

選擇記錄輸出檢視。

如果設定為 false，則不同測試檔案的記錄將會即時列印。請注意，在平行執行時，這可能會導致來自不同檔案的記錄輸出混合在一起。

如果設定為 true，則記錄輸出將依測試規格分組，並且僅在測試規格完成時列印。

預設情況下，設定為 false，因此記錄會即時列印。

類型：Boolean
預設值：false

services​

服務會接管您不想處理的特定工作。它們幾乎毫不費力地增強您的測試設定。

類型：String[]|Object[]
預設值：[]

framework​

定義 WDIO testrunner 要使用的測試框架。

類型：String
預設值：mocha
選項：mocha | jasmine

mochaOpts、jasmineOpts 和 cucumberOpts​

特定於框架的選項。請參閱框架配接器文件，了解哪些選項可用。請在 框架中閱讀更多相關資訊。

類型：Object
預設值：{ timeout: 10000 }

cucumberFeaturesWithLineNumbers​

帶有行號的 cucumber 功能清單（當 使用 cucumber 框架時）。

類型：String[] 預設值：[]

reporters​

要使用的報告器清單。報告器可以是字串，也可以是 ['reporterName', { /* 報告器選項 */}] 的陣列，其中第一個元素是帶有報告器名稱的字串，而第二個元素是帶有報告器選項的物件。

類型：String[]|Object[]
預設值：[]

範例

reporters: [
    'dot',
    'spec'
    ['junit', {
        outputDir: `${__dirname}/reports`,
        otherOption: 'foobar'
    }]
]

reporterSyncInterval​

決定報告器如果非同步報告其記錄（例如，如果記錄串流到第三方供應商）時，應以哪個間隔檢查它們是否已同步。

類型：Number
預設值：100 (ms)

reporterSyncTimeout​

決定報告器完成上傳其所有記錄的最大時間，直到 testrunner 擲回錯誤。

類型：Number
預設值：5000 (ms)

execArgv​

啟動子程序時要指定的 Node 引數。

類型：String[]
預設值：null

filesToWatch​

支援 glob 的字串模式清單，這些模式會告知 testrunner 在使用 --watch 旗標執行時，額外監視其他檔案（例如應用程式檔案）。預設情況下，testrunner 已監視所有規格檔案。

類型：String[]
預設值：[]

updateSnapshots​

如果要更新快照，請設定為 true。理想情況下，作為 CLI 參數的一部分使用，例如 wdio run wdio.conf.js --s。

類型：'new' | 'all' | 'none'
預設值：如果在 CI 中執行且未提供則為 none，如果未提供則為 new，否則為所提供的內容

resolveSnapshotPath​

覆寫預設快照路徑。例如，將快照儲存在測試檔案旁邊。

wdio.conf.ts
export const config: WebdriverIO.Config = {
    resolveSnapshotPath: (testPath, snapExtension) => testPath + snapExtension,
}

類型：(testPath: string, snapExtension: string) => string
預設值：將快照檔案儲存在測試檔案旁邊的 __snapshots__ 目錄中

tsConfigPath​

WDIO 使用 tsx 來編譯 TypeScript 檔案。您的 TSConfig 會從目前的工作目錄自動偵測，但您可以在此處指定自訂路徑，或設定 TSX_TSCONFIG_PATH 環境變數。

請參閱 tsx 文件：https://tsx.is/usage#custom-tsconfig-json-path

類型：String
預設值：null

Hooks​

WDIO testrunner 允許您設定在測試生命週期的特定時間觸發的 hook。這允許自訂動作（例如，在測試失敗時擷取螢幕快照）。

每個 Hook 都有關於生命週期的特定資訊作為參數（例如，關於測試套件或測試的資訊）。請在我們的範例配置中閱讀更多關於所有 Hook 屬性的資訊。

注意： 有些 Hook（onPrepare、onWorkerStart、onWorkerEnd 和 onComplete）是在不同的進程中執行的，因此無法與在 worker 進程中執行的其他 Hook 共享任何全域資料。

onPrepare​

在所有 worker 啟動之前執行一次。

參數

  • config (object)：WebdriverIO 配置物件
  • param (object[])：功能詳細資料列表

onWorkerStart​

在 worker 進程產生之前執行，可用於初始化該 worker 的特定服務，以及以非同步方式修改執行時環境。

參數

  • cid (string)：功能 ID（例如 0-0）
  • caps (object)：包含將在 worker 中產生的會話功能
  • specs (string[])：要在 worker 進程中執行的規格
  • args (object)：一旦 worker 初始化後將與主要配置合併的物件
  • execArgv (string[])：傳遞給 worker 進程的字串引數列表

onWorkerEnd​

在 worker 進程結束後立即執行。

參數

  • cid (string)：功能 ID（例如 0-0）
  • exitCode (number)：0 - 成功，1 - 失敗
  • specs (string[])：要在 worker 進程中執行的規格
  • retries (number)：規格層級重試次數，如「在每個規格檔案上新增重試」中所定義

beforeSession​

在初始化 webdriver 會話和測試框架之前執行。它允許您根據功能或規格操作配置。

參數

  • config (object)：WebdriverIO 配置物件
  • caps (object)：包含將在 worker 中產生的會話功能
  • specs (string[])：要在 worker 進程中執行的規格

before​

在測試執行開始之前執行。此時您可以存取所有全域變數，例如 browser。這是定義自訂命令的理想位置。

參數

  • caps (object)：包含將在 worker 中產生的會話功能
  • specs (string[])：要在 worker 進程中執行的規格
  • browser (object)：已建立的瀏覽器/裝置會話實例

beforeSuite​

在套件開始之前執行的 Hook（僅限 Mocha/Jasmine）

參數

  • suite (object)：套件詳細資料

beforeHook​

在套件中的 Hook 開始之前執行的 Hook（例如，在 Mocha 中呼叫 beforeEach 之前執行）

參數

  • test (object)：測試詳細資料
  • context (object)：測試上下文（在 Cucumber 中代表 World 物件）

afterHook​

在套件中的 Hook 結束之後執行的 Hook（例如，在 Mocha 中呼叫 afterEach 之後執行）

參數

  • test (object)：測試詳細資料
  • context (object)：測試上下文（在 Cucumber 中代表 World 物件）
  • result (object)：Hook 結果（包含 error、result、duration、passed、retries 屬性）

beforeTest​

在測試之前執行的函數（僅限 Mocha/Jasmine）。

參數

  • test (object)：測試詳細資料
  • context (object)：執行測試的範圍物件

beforeCommand​

在執行 WebdriverIO 命令之前執行。

參數

  • commandName (string)：命令名稱
  • args (*)：命令將接收的引數

afterCommand​

在執行 WebdriverIO 命令之後執行。

參數

  • commandName (string)：命令名稱
  • args (*)：命令將接收的引數
  • result (number)：0 - 命令成功，1 - 命令錯誤
  • error (Error)：如果有的話，錯誤物件

afterTest​

在測試結束後執行的函數（在 Mocha/Jasmine 中）。

參數

  • test (object)：測試詳細資料
  • context (object)：執行測試的範圍物件
  • result.error (Error)：如果測試失敗，則為錯誤物件，否則為 undefined
  • result.result (Any)：測試函數的傳回物件
  • result.duration (Number)：測試持續時間
  • result.passed (Boolean)：如果測試通過，則為 true，否則為 false
  • result.retries (Object)：關於單一測試相關重試的資訊，如為Mocha 和 Jasmine 以及Cucumber 所定義，例如 { attempts: 0, limit: 0 }，請參閱
  • result (object)：Hook 結果（包含 error、result、duration、passed、retries 屬性）

afterSuite​

在套件結束後執行的 Hook（僅限 Mocha/Jasmine）

參數

  • suite (object)：套件詳細資料

after​

在所有測試完成後執行。您仍然可以存取測試中的所有全域變數。

參數

  • result (number)：0 - 測試通過，1 - 測試失敗
  • caps (object)：包含將在 worker 中產生的會話功能
  • specs (string[])：要在 worker 進程中執行的規格

afterSession​

在終止 webdriver 會話後立即執行。

參數

  • config (object)：WebdriverIO 配置物件
  • caps (object)：包含將在 worker 中產生的會話功能
  • specs (string[])：要在 worker 進程中執行的規格

onComplete​

在所有 worker 關閉且進程即將結束時執行。在 onComplete Hook 中拋出的錯誤將導致測試執行失敗。

參數

  • exitCode (number)：0 - 成功，1 - 失敗
  • config (object)：WebdriverIO 配置物件
  • caps (object)：包含將在 worker 中產生的會話功能
  • result (object)：包含測試結果的結果物件

onReload​

在發生重新整理時執行。

參數

  • oldSessionId (string)：舊會話的會話 ID
  • newSessionId (string)：新會話的會話 ID

beforeFeature​

在 Cucumber 功能之前執行。

參數

afterFeature​

在 Cucumber 功能之後執行。

參數

beforeScenario​

在 Cucumber 情境之前執行。

參數

  • world (ITestCaseHookParameter)：包含有關 pickle 和測試步驟資訊的 world 物件
  • context (object)：Cucumber World 物件

afterScenario​

在 Cucumber 情境之後執行。

參數

  • world (ITestCaseHookParameter)：包含有關 pickle 和測試步驟資訊的 world 物件
  • result (object)：包含情境結果的結果物件
  • result.passed (boolean)：如果情境通過，則為 true
  • result.error (string)：如果情境失敗，則為錯誤堆疊
  • result.duration (number)：情境的持續時間（以毫秒為單位）
  • context (object)：Cucumber World 物件

beforeStep​

在 Cucumber 步驟之前執行。

參數

  • step (Pickle.IPickleStep)：Cucumber 步驟物件
  • scenario (IPickle)：Cucumber 情境物件
  • context (object)：Cucumber World 物件

afterStep​

在 Cucumber 步驟之後執行。

參數

  • step (Pickle.IPickleStep)：Cucumber 步驟物件
  • scenario (IPickle)：Cucumber 情境物件
  • result：(object)：包含步驟結果的結果物件
  • result.passed (boolean)：如果情境通過，則為 true
  • result.error (string)：如果情境失敗，則為錯誤堆疊
  • result.duration (number)：情境的持續時間（以毫秒為單位）
  • context (object)：Cucumber World 物件

beforeAssertion​

在發生 WebdriverIO 斷言之前執行的 Hook。

參數

  • params：斷言資訊
  • params.matcherName (string)：匹配器的名稱（例如 toHaveTitle）
  • params.expectedValue：傳遞到匹配器的值
  • params.options：斷言選項

afterAssertion​

在發生 WebdriverIO 斷言之後執行的 Hook。

參數

  • params：斷言資訊
  • params.matcherName (string)：匹配器的名稱（例如 toHaveTitle）
  • params.expectedValue：傳遞到匹配器的值
  • params.options：斷言選項
  • params.result：斷言結果

歡迎！我能如何幫您？

WebdriverIO AI Copilot