設定檔

概述 #

為了更好地為您服務，Karma 需要了解您的專案才能進行測試，這是透過設定檔來完成的。產生初始設定檔最簡單的方法是使用 karma init 命令。此頁面列出了所有可用的設定選項。

注意

大多數框架轉接器、報告器、預處理器和啟動器都需要作為 插件 載入。

Karma 設定檔可以用 JavaScript、CoffeeScript 或 TypeScript 撰寫，並作為常規 Node.js 模組載入。

除非作為參數提供，否則 Karma CLI 將按以下順序尋找設定檔

  • ./karma.conf.js
  • ./karma.conf.coffee
  • ./karma.conf.ts
  • ./.config/karma.conf.js
  • ./.config/karma.conf.coffee
  • ./.config/karma.conf.ts

。

在設定檔中，設定程式碼是透過將 module.exports 指向一個接受一個參數（設定物件）的函數來組合在一起的。

// karma.conf.js
module.exports = function(config) {
  config.set({
    basePath: '../..',
    frameworks: ['jasmine'],
    //...
  });
};

# karma.conf.coffee
module.exports = (config) ->
  config.set
    basePath: '../..'
    frameworks: ['jasmine']
    # ...

// karma.conf.ts
module.exports = (config) => {
  config.set({
    basePath: '../..',
    frameworks: ['jasmine'],
    //...
  });
}

或者，您可以改用 async 函數（自 v6.3 起）。

// karma.conf.js
module.exports = async (config) => {
  const karmaConfig = await getKarmaConfig("dev");
  
  config.set({
    ...karmaConfig
  });
};

自訂 TypeScript 設定 #

在底層，Karma 使用 ts-node 將 TypeScript 轉譯為 JavaScript。如果解析的 tsconfig.json 將 module 設定為 ES 格式，您可能會收到類似 SyntaxError: Unexpected token 的錯誤。這是因為 Node 中不支援 ES 模組格式。要克服此問題，您需要將 ts-node 設定為使用 commonjs 模組格式。

建立一個覆蓋模組格式的 JavaScript 設定檔。

// karma.conf.js
require('ts-node').register({
  compilerOptions: {
    module: 'commonjs'
  }
});
require('./karma.conf.ts');

檔案模式 #

所有指定檔案路徑的設定選項都使用 minimatch 函式庫來促進靈活但簡潔的檔案表達式，以便您可以輕鬆地列出您想要包含和排除的所有檔案。

您可以在以下章節中找到每個設定選項的詳細資訊。以下選項使用 minimatch 表達式

  • exclude
  • files
  • preprocessors

範例

  • **/*.js：所有子目錄中具有 "js" 副檔名的所有檔案
  • **/!(jquery).js：與前一個相同，但不包括 "jquery.js"
  • **/(foo|bar).js：在所有子目錄中，所有 "foo.js" 或 "bar.js" 檔案

設定選項 #

以下是所有可用的設定選項。

autoWatch #

類型： 布林值

預設值： true

CLI： --auto-watch, --no-auto-watch

說明： 啟用或停用監控檔案並在其中一個檔案變更時執行測試。

autoWatchBatchDelay #

類型： 數字

預設值： 250

說明： 當 Karma 監控檔案的變更時，它會嘗試將多個變更批次處理成單次執行，以便測試執行器不會嘗試過度啟動和重新啟動測試，或在建置檔案處於不一致狀態時重新啟動。設定設定會告知 Karma 在再次啟動測試流程之前，從上次檔案變更開始等待多長時間（以毫秒為單位），並在每次檔案變更時重置計時器（即 防抖動）。

basePath #

類型： 字串

預設值： ''

說明： 將用於解析 files 和 exclude 中定義的所有相對路徑的根路徑位置。如果 basePath 設定是相對路徑，則它將解析為設定檔的 __dirname。

browserDisconnectTimeout #

類型： 數字

預設值： 2000

說明： Karma 等待瀏覽器重新連線的時間（以毫秒為單位）。

使用不穩定的連線時，瀏覽器斷線是很常見的，但實際的測試執行仍然沒有任何問題。Karma 並不將斷線視為立即失敗，而是會等待 browserDisconnectTimeout（毫秒）。如果瀏覽器在那段時間內重新連線，一切都沒問題。

browserConsoleLogOptions #

類型： 物件

預設值： {level: "debug", format: "%b %T: %m", terminal: true}

說明： 使用以下屬性設定瀏覽器控制台的記錄方式，所有屬性都是可選的

{
  level:  string,
  format: string,
  path:   string,
  terminal: boolean
}

這裡的 level 是所需的日誌級別，其中級別 log 永遠會被記錄。格式是一個字串，其中 %b、%t、%T 和 %m 分別替換為瀏覽器字串、小寫日誌類型、大寫日誌類型和日誌訊息。此格式僅影響輸出檔案。path 是輸出檔案的輸出路徑，terminal 指示日誌是否應寫入終端機。

browserDisconnectTolerance #

類型： 數字

預設值： 0

說明： 可容忍的斷線次數。

disconnectTolerance 值表示瀏覽器在斷線情況下嘗試連線的最大次數。通常，任何斷線都被視為失敗，但是此選項允許您在 Karma 伺服器和瀏覽器之間的網路連結不穩定時定義容忍級別。

browserNoActivityTimeout #

類型： 數字

預設值： 30000

說明： Karma 在與瀏覽器斷線之前會等待來自瀏覽器的訊息多長時間（以毫秒為單位）。

如果在測試執行期間，Karma 在 browserNoActivityTimeout（毫秒）內沒有收到來自瀏覽器的任何訊息，它將與瀏覽器斷線。預設值是 Travis 建議的值 (https://docs.travis-ci.com/user/gui-and-headless-browsers/#karma-and-firefox-inactivity-timeouts)

browsers #

類型： 陣列

預設值： []

CLI： --browsers Chrome,Firefox, --no-browsers

可能的值

  • Chrome（啟動器需要 karma-chrome-launcher 插件）
  • ChromeCanary（啟動器需要 karma-chrome-launcher 插件）
  • ChromeHeadless（啟動器需要 karma-chrome-launcher 插件 ^2.1.0）
  • PhantomJS（啟動器需要 karma-phantomjs-launcher 插件）
  • Firefox（啟動器需要 karma-firefox-launcher 插件）
  • Opera（啟動器需要 karma-opera-launcher 插件）
  • IE（啟動器需要 karma-ie-launcher 插件）
  • Safari（啟動器需要 karma-safari-launcher 插件）

說明： 要啟動和捕捉的瀏覽器列表。當 Karma 啟動時，它也會啟動此設定中放置的每個瀏覽器。一旦 Karma 關閉，它也會關閉這些瀏覽器。您可以透過開啟瀏覽器並訪問 Karma 網路伺服器正在監聽的 URL（預設為 https://127.0.0.1:9876/）來手動捕捉任何瀏覽器。

有關更多資訊，請參閱 config/browsers。可以透過 插件 定義其他啟動器。使用 --no-browsers 命令列選項可以使用空列表覆蓋設定檔中指定的此設定的值。

captureTimeout #

類型： 數字

預設值： 60000

說明： 捕捉瀏覽器的逾時時間（以毫秒為單位）。

captureTimeout 值表示允許瀏覽器啟動並連線到 Karma 的最大啟動時間。如果任何瀏覽器在逾時時間內未被捕捉，Karma 將會終止它並嘗試再次啟動它，並且在三次嘗試捕捉它之後，Karma 將會放棄。

client.args #

類型： 陣列

預設值： undefined

CLI： -- 之後的所有參數（僅在使用 karma run 時）

說明： 當 karma run 在命令列上传递额外的参数时，它们会作为 karma.config.args（字符串数组）传递给测试适配器。client.args 选项允许您为除 run 以外的操作设置此值。

如何使用此值取决于您的测试适配器 - 您应该查看适配器的文档以了解它如何（以及是否）使用此值。

client.useIframe #

類型： 布林值

預設值： true

說明： 在 iFrame 或新視窗中執行測試

如果為 true，Karma 會在 iFrame 中執行測試。如果為 false，Karma 會在新視窗中執行測試。某些測試可能無法在 iFrame 中執行，並且可能需要新視窗才能執行。

client.runInParent #

類型： 布林值

預設值： false

說明： 在與客戶端相同的視窗中執行測試，而不使用 iframe 或新視窗

如果為 true，Karma 會在原始視窗中執行測試，而不使用 iframe。它將動態載入測試腳本。

client.captureConsole #

類型： 布林值

預設值： true

說明： 捕捉所有控制台輸出並将其管道傳輸到終端機。

client.clearContext #

類型： 布林值

預設值： true

說明： 清除上下文視窗

如果為 true，Karma 會在完成測試執行後清除上下文視窗。如果為 false，Karma 不會在完成測試執行後清除上下文視窗。當嵌入 Jasmine Spec Runner 範本時，將此設定為 false 很有用。

client.clientDisplayNone #

類型： 布林值

預設值： false

說明： 在客戶端元素上設定樣式顯示為 none。

如果為 true，Karma 不會顯示橫幅和瀏覽器列表。在使用 karma 進行帶有螢幕截圖的組件測試時很有用。

client.allowedReturnUrlPatterns #

類型： 陣列

預設值： ['^https?://']

說明： 定義將允許用於 return_url 查詢參數的正則表達式的字串表示形式。

如果 return_url 查詢參數的值與由此陣列的每個元素的字串表示形式派生的任何正則表達式不匹配，則將阻止導航到它。

colors #

類型： 布林值

預設值： true

CLI： --colors, --no-colors

說明： 啟用或停用輸出（報告器和日誌）中的顏色。

concurrency #

類型： 數字

預設值： Infinity

說明： Karma 並行啟動的瀏覽器數量。

尤其是在 SauceLabs 和 Browserstack 等服務上，一次只啟動有限數量的瀏覽器，並且只有在這些瀏覽器完成後才啟動更多瀏覽器才有意義。使用此設定，您可以指定在任何給定時間點應該同時運行的瀏覽器數量。

crossOriginAttribute #

類型： 布林值

預設值： true

說明：若為 true，則會將 crossorigin 屬性附加到產生的 script 標籤，這可讓從不同來源提供的 JavaScript 檔案有更好的錯誤報告。當您需要載入未提供必要的 Access-Control-Allow-Origin 標頭的外部腳本時，請停用此功能。

customContextFile #

類型：字串

預設值： null

說明：若為 null（預設值），則使用 Karma 自身的 context.html 檔案。

customDebugFile #

類型：字串

預設值： null

說明：若為 null（預設值），則使用 Karma 自身的 debug.html 檔案。

customClientContextFile #

類型：字串

預設值： null

說明：若為 null（預設值），則使用 Karma 自身的 client_with_context.html 檔案（當 client.runInParent 設為 true 時使用）。

customHeaders #

類型： 陣列

預設值： undefined

說明自訂 HTTP 標頭，這些標頭會在 Karma 的網路伺服器提供檔案時設定。自訂標頭很有用，尤其是在即將推出的瀏覽器功能（如 Service Workers）中。

customHeaders 選項允許您為符合正規表達式的檔案設定 HTTP 標頭。customHeaders 是一個 Objects 陣列，其屬性如下：

  • match：用於匹配檔案的正規表達式字串
  • name：HTTP 標頭名稱
  • value：HTTP 標頭值

範例

customHeaders: [{
  match: '.*foo.html',
  name: 'Service-Worker-Allowed',
  value: '/'
}]

detached #

類型： 布林值

預設值： false

CLI： --detached

說明：若為 true，則會在另一個程序中啟動 Karma 伺服器，且不會將任何輸出寫入控制台。可以使用 karma stop 命令停止伺服器。

exclude #

類型： 陣列

預設值： []

說明：要從載入的檔案中排除的檔案/模式清單。

failOnEmptyTestSuite #

類型： 布林值

預設值： true

CLI： --fail-on-empty-test-suite、--no-fail-on-empty-test-suite

說明：啟用或停用在執行空的測試套件時失敗。如果停用，程式將返回退出代碼 0 並顯示警告。

failOnSkippedTests #

類型： 布林值

預設值： false

CLI： --fail-on-skipped-tests、--no-fail-on-skipped-tests

說明：啟用或停用在刻意停用的測試（例如 Jasmine 中的 fit() 或 xit() 測試）上失敗。使用此選項可防止意外停用驗證產品所需的測試。

failOnFailingTestSuite #

類型： 布林值

預設值： true

CLI： --fail-on-failing-test-suite、--no-fail-on-failing-test-suite

說明：啟用或停用在失敗的測試上失敗。

files #

類型： 陣列

預設值： []

說明：要在瀏覽器中載入的檔案/模式清單。

請參閱config/files以取得更多資訊。

forceJSONP #

類型： 布林值

預設值： false

說明：強制 socket.io 使用 JSONP 輪詢而不是 XHR 輪詢。

frameworks #

類型： 陣列

預設值： []

說明：您想要使用的測試框架清單。通常，您會將其設定為 ['jasmine']、['mocha'] 或 ['qunit'] 等。

請注意，Karma 中幾乎所有框架都需要安裝額外的插件/框架程式庫（透過 npm）。

您可以在插件中找到其他資訊。

listenAddress #

類型： 字串

預設值： '0.0.0.0' 或 LISTEN_ADDR

說明：伺服器將監聽的地址。更改為 'localhost' 以僅監聽迴路，或更改為 '::' 以監聽所有 IPv6 介面。

hostname #

類型： 字串

預設值： 'localhost'

說明：擷取瀏覽器時要使用的主機名稱。

httpsServerOptions #

類型： 物件

預設值： {}

說明：Node 的 https 類別將使用的選項物件。

您可以在NodeJS.org API 文件中找到物件說明。

範例

httpsServerOptions: {
  key: fs.readFileSync('server.key', 'utf8'),
  cert: fs.readFileSync('server.crt', 'utf8')
},

logLevel #

類型：常數

預設值： config.LOG_INFO

CLI： --log-level debug

可能的值

  • config.LOG_DISABLE
  • config.LOG_ERROR
  • config.LOG_WARN
  • config.LOG_INFO
  • config.LOG_DEBUG

說明：記錄級別。

loggers #

類型： 陣列

預設值： [{type: 'console'}]

說明：要使用的日誌附加程式清單。請參閱log4js的文件以取得更多資訊。

middleware #

類型： 陣列

預設值： []

說明：您希望 Karma 伺服器使用的其他中介軟體名稱清單。中介軟體將按列出的順序使用。

您必須透過插件/框架（內聯或透過 npm）安裝中介軟體。您可以在插件中找到其他資訊。

插件必須提供 express/connect 中介軟體函數（您可以在Express 文件中找到相關詳細資訊）。自訂內聯中介軟體的範例如下所示。

範例

function CustomMiddlewareFactory (config) {
  return function (request, response, /* next */) {
    response.writeHead(200)
    return response.end("content!")
  }
}

middleware: ['custom']
plugins: [
  {'middleware:custom': ['factory', CustomMiddlewareFactory]}
  ...
]

mime #

類型： 物件

預設值： {}

說明：重新定義從檔案副檔名到 MIME 類型的預設映射。

將屬性名稱設定為所需的 MIME，並提供副檔名陣列（不含點）作為其值。

範例

mime: {
   'text/x-typescript': ['ts','tsx']
   'text/plain' : ['mytxt']
}

beforeMiddleware #

類型： 陣列

預設值： []

說明：這與中介軟體相同，只是這些中介軟體將在 Karma 自身的中介軟體之前執行。

plugins #

類型： 陣列

預設值： ['karma-*']

說明：要載入的插件清單。插件可以是插件物件，也可以是包含匯出插件物件的模組名稱的字串。請參閱插件以取得有關如何安裝和使用插件的更多資訊。

預設情況下，Karma 會從所有名稱以 karma-* 開頭的同級 npm 套件載入插件。

port #

類型： 數字

預設值： 9876

CLI： --port 9876

說明：網路伺服器將監聽的埠。

如果定義的埠已被使用，Karma 將自動以 1 為增量遞增其值，直到找到可用的埠。

processKillTimeout #

類型： 數字

預設值： 2000

說明：Karma 在發送 SIGKILL 訊號之前會等待瀏覽器程序終止的時間（以毫秒為單位）。

如果在測試執行後或 Karma 嘗試結束瀏覽器後，瀏覽器未在 processKillTimeout（毫秒）內結束，則 Karma 將發送 SIGKILL 訊號以嘗試強制結束瀏覽器。

preprocessors #

類型： 物件

預設值： {'**/*.coffee': 'coffee'}

說明：要使用的預處理器映射。

可以透過插件載入預處理器。

注意

Karma 中幾乎所有預處理器都需要安裝額外的程式庫（透過 npm）。

請注意，預處理器可能會轉換執行階段可用的檔案和檔案類型。例如，如果您在原始程式碼檔案上使用「coverage」預處理器，那麼當您嘗試以互動方式偵錯測試時，您會發現預期的原始程式碼與您的預期完全不同。因此，您需要進行設計，以便自動化建置使用「reporters」清單中的 coverage 項目，但互動式偵錯不使用。

點擊此處以取得更多資訊。

protocol #

類型： 字串

預設值： 'http:'

可能的值

  • http
  • https

說明：用於執行 Karma 網路伺服器的通訊協定。

決定是否使用 Node http 或 https 類別。

注意

使用 'https:' 需要您指定 httpsServerOptions。

httpModule #

類型： 字串

預設值： undefined

說明：Karma 網路伺服器使用的模組。

使用提供的模組，而不是 node 內建的 http 或 https 模組。在此載入的模組必須與 node 的 http 模組的介面完全匹配。這對於載入 node-http2 之類的模組以支援 http2 很有用。

注意

如果您使用此選項來啟用 http2，則還必須將 protocol 設定為 https: 並指定憑證，因為 http2 只能透過 https 執行。

proxies #

類型： 物件

預設值： {}

說明：路徑-代理配對的映射。

代理可以由目標網址或路徑直接指定，也可以使用物件來配置更多選項。可用的選項如下：

  • target 目標網址或路徑（必填）
  • changeOrigin 代理是否應使用目標中的主機覆蓋 Host 標頭（預設為 false）

範例

proxies: {
  '/static': 'http://gstatic.com',
  '/web': 'https://127.0.0.1:9000',
  '/img/': '/base/test/images/',
  '/proxyfied': {
    'target': 'http://myserver.localhost',
    'changeOrigin': true
  }
},

proxyValidateSSL #

類型： 布林值

預設值： true

說明：當發現無效的 SSL 憑證時，Karma 或任何瀏覽器是否應引發錯誤。

reportSlowerThan #

類型： 數字

預設值： 0

說明：Karma 將報告所有執行時間超過指定時間限制（以毫秒為單位）的測試。預設情況下會停用此功能（因為預設值為 0）。

reporters #

類型： 陣列

預設值： ['progress']

CLI： --reporters progress,growl

可能的值

  • dots
  • progress

說明：要使用的報告器清單。

可以透過插件載入其他報告器，例如 growl、junit、teamcity 或 coverage。

注意

Karma 中幾乎所有其他報告器（progress 除外）都需要安裝額外的程式庫（透過 npm）。

formatError #

類型：函數

預設值： undefined

CLI： --format-error ./path/to/formatFunction.js

參數

  • msg - 斷言錯誤和堆疊追蹤的單行（針對每一行呼叫）。

返回值：新的錯誤訊息行。

說明：格式化斷言錯誤和堆疊追蹤。可用於移除廠商和已編譯的原始程式碼。返回空行 '' 以移除它。

CLI 選項應該是匯出格式函數的檔案的路徑。這可以是在模組根目錄匯出的函數，也可以是名為 formatError 的匯出。

pingTimeout #

類型 數字

預設值 5000

說明 Socket.io pingTimeout（以毫秒為單位），https://socketio.dev.org.tw/docs/server-api/#new-Server-httpServer-options。非常慢的網路可能需要高達 60000 的值。較大的值會延遲發現測試中的死結或瀏覽器當機。

restartOnFileChange #

類型： 布林值

預設值： false

說明：當 Karma 正在監控檔案的變更時，它會延遲新的執行，直到目前的執行完成。啟用此設定將取消目前的執行，並在偵測到變更時立即開始新的執行。

retryLimit #

類型： 數字

預設值 2

說明：當瀏覽器當機時，Karma 將嘗試重新啟動。這定義了 Karma 在放棄之前應重新啟動瀏覽器的次數。

singleRun #

類型： 布林值

預設值： false

CLI： --single-run、--no-single-run

說明：持續整合模式。

若為 true，Karma 將啟動並擷取所有已配置的瀏覽器，執行測試，然後根據所有測試是否通過或是否有任何測試失敗，以退出代碼 0 或 1 退出。

transports #

類型： 陣列

預設值： ['polling', 'websocket']

說明：瀏覽器和測試伺服器之間允許的傳輸方法陣列。此配置設定會傳遞給socket.io（它管理瀏覽器和測試伺服器之間的通訊）。

proxyReq #

類型：函數

預設值： undefined

說明：在請求代理時呼叫。

關於這方面的詳細資訊，可以參考 node-http-proxy。以下顯示覆寫 HTTP 標頭的範例。

範例

proxyReq: function(proxyReq, req, res, options) {
  proxyReq.setHeader('Referer', 'https://www.example.com/');
}

proxyRes #

類型：函數

預設值： undefined

說明：在 Proxy 回應時呼叫。

關於這方面的詳細資訊，可以參考 node-http-proxy。以下顯示覆寫 HTTP 標頭的範例。

範例

proxyRes: function(proxyRes, req, res) {
  if (proxyRes.headers['set-cookie']) {
    proxyRes.headers['set-cookie'] = proxyRes.headers['set-cookie'].map(function (cookie) {
      return cookie.replace(/\s*secure;?/i, '');
    })
  }
}

upstreamProxy #

類型： 物件

預設值： undefined

說明：當 Karma 伺服器需要在會更改基本網址等的代理伺服器後端執行時使用

如果設定，則會定義以下欄位，並且可以覆寫

path #

類型： 字串

預設值： '/'

說明：啟動瀏覽器時會加在基本網址前面，並加在瀏覽器載入的內部網址前面

port #

類型： 數字

預設值： 9875

說明：啟動瀏覽器時將用作連接埠

hostname #

類型： 字串

預設值： 'localhost'

說明：啟動瀏覽器時將用作主機名稱

protocol #

類型： 字串

預設值： 'http:'

說明：啟動瀏覽器時將用作通訊協定

urlRoot #

類型： 字串

預設值： '/'

說明：Karma 執行的基本網址。

所有 Karma 的網址都會加上 urlRoot 前綴。這在使用代理伺服器時很有用，因為有時您可能想要代理 Karma 已經使用的網址。

browserSocketTimeout #

類型： 數字

預設值： 20000

說明：用戶端 Socket 連線逾時（以毫秒為單位）。

此設定代表用戶端等待 Socket 連線的時間。

在不同環境中執行瀏覽器時，用戶端 Socket 連線所需的時間可能不同。如果 Karma 無法在預設逾時內連線，您可能會看到類似以下的錯誤

ChromeHeadless has not captured in 60000ms, killing.
Trying to start ChromeHeadless again (1/2).
ChromeHeadless has not captured in 60000ms, killing.
Trying to start ChromeHeadless again (2/2).
ChromeHeadless has not captured in 60000ms, killing.
ChromeHeadless failed 2 times(timeout). Giving up.

如果您看到此錯誤，可以嘗試增加 Socket 連線逾時。