配置文件

概述 #

为了更好地服务于您，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.cn/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 Web 服务器正在监听的 URL 来手动捕获任何浏览器（默认情况下为 http://localhost: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 或新窗口中运行测试

如果为真，则 Karma 在 iFrame 中运行测试。如果为假，则 Karma 在新窗口中运行测试。某些测试可能无法在 iFrame 中运行，可能需要一个新窗口才能运行。

client.runInParent #

类型：布尔值

默认值：false

描述：在与客户端相同的窗口上运行测试，无需使用 iframe 或新窗口

如果为真，则 Karma 在原始窗口内运行测试，无需使用 iframe。它将动态加载测试脚本。

client.captureConsole #

类型：布尔值

默认值：true

描述：捕获所有控制台输出并将其传递到终端。

client.clearContext #

类型：布尔值

默认值：true

描述：清除上下文窗口

如果为真，则 Karma 在运行测试完成后清除上下文窗口。如果为假，则 Karma 在运行测试完成后不会清除上下文窗口。当嵌入 Jasmine Spec Runner 模板时，将此设置为 false 很有用。

client.clientDisplayNone #

类型：布尔值

默认值：false

描述：在客户端元素上设置样式 display none。

如果为真，则 Karma 不会显示横幅和浏览器列表。在使用 karma 进行带有屏幕截图的组件测试时很有用。

client.allowedReturnUrlPatterns #

类型：数组

默认值：['^https?://']

描述：定义将允许用于 return_url 查询参数的正则表达式的字符串表示形式。

如果 return_url 查询参数的值与从此数组的每个元素的字符串表示形式派生的任何正则表达式都不匹配，则将阻止导航到它。

colors #

类型：布尔值

默认值：true

CLI：--colors、--no-colors

描述：启用或禁用输出（报告器和日志）中的颜色。

concurrency #

类型：数字

默认值：Infinity

描述：Karma 并行启动的浏览器数量。

尤其是在 SauceLabs 和 Browserstack 等服务上，一次只启动有限数量的浏览器才有意义，并且只有在这些浏览器完成后才启动更多浏览器。使用此配置，您可以指定在任何给定时间一次应该运行多少个浏览器。

crossOriginAttribute #

类型：布尔值

默认值：true

描述：设置为 true 时，将在生成的脚本标签中添加 crossorigin 属性，这将为从不同来源提供的 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

描述 Karma 的 Web 服务器在提供文件时将设置的自定义 HTTP 标头。自定义标头非常有用，尤其是在即将推出的浏览器功能（如 Service Workers）中。

customHeaders 选项允许您为与正则表达式匹配的文件设置 HTTP 标头。customHeaders 是一个 对象数组，具有以下属性

  • 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）。

可以在 plugins 中找到更多信息。

listenAddress #

类型：字符串

默认值：'0.0.0.0' or 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）安装了中间件。可以在 plugins 中找到更多信息。

该插件必须提供一个 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-*']

描述：要加载的插件列表。插件可以是插件对象，也可以是包含导出插件对象的模块名称的字符串。有关如何安装和使用插件的更多信息，请参阅 plugins。

默认情况下，Karma 会加载所有同级 npm 包中的插件，这些插件的名称以 karma-* 开头。

port #

类型：数字

默认值：9876

CLI：--port 9876

描述：Web 服务器将监听的端口。

如果定义的端口已被使用，Karma 将自动将其值增加 1，直到找到空闲端口。

processKillTimeout #

类型：数字

默认值：2000

描述：Karma 在发送 SIGKILL 信号之前将等待浏览器进程终止多长时间。

如果在测试执行或 Karma 尝试终止浏览器后，浏览器在 processKillTimeout（毫秒）内未终止，Karma 将发送 SIGKILL 信号以强制尝试终止浏览器。

preprocessors #

类型：对象

默认值：{'**/*.coffee': 'coffee'}

描述：要使用的预处理器映射。

预处理器可以通过 plugins 加载。

注意

Karma 中几乎所有预处理器都需要安装额外的库（通过 npm）。

请注意，预处理器可能会转换运行时可用的文件和文件类型。例如，如果您在源文件上使用“coverage”预处理器，然后尝试交互式调试测试，您会发现您期望的源代码与您期望的完全不同。因此，您需要设计此方案，以便您的自动化构建使用“reporters”列表中的 coverage 条目，但您的交互式调试不使用。

单击 此处 获取更多信息。

protocol #

类型：字符串

默认值：'http:'

可能的值

  • http
  • https

描述：用于运行 Karma Web 服务器的协议。

确定使用 Node 的 http 或 https 类。

注意

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

httpModule #

类型：字符串

默认值：undefined

描述：Karma Web 服务器使用的模块。

使用提供的模块而不是 Node 的内置 http 或 https 模块。此处加载的模块必须完全匹配 Node 的 http 模块的接口。这对于加载 node-http2 等模块以允许 http2 支持非常有用。

注意

如果您使用此功能启用 http2，则还必须将 protocol 设置为 https: 并指定证书，因为 http2 只能在 https 上运行。

proxies #

类型：对象

默认值：{}

描述：路径-代理对的映射。

可以直接通过目标 URL 或路径指定代理，或者使用对象配置更多选项。可用的选项是

  • target 目标 URL 或路径（必填）
  • changeOrigin 代理是否应使用目标的主机覆盖 Host 标头（默认为 false）

示例

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

proxyValidateSSL #

类型：布尔值

默认值：true

描述：Karma 或任何浏览器在找到无效的 SSL 证书时是否应引发错误。

reportSlowerThan #

类型：数字

默认值：0

描述：Karma 将报告所有比给定时间限制（以毫秒为单位）慢的测试。默认情况下禁用此功能（因为默认值为 0）。

reporters #

类型：数组

默认值：['progress']

CLI：--reporters progress,growl

可能的值

  • dots
  • progress

描述：要使用的报告程序列表。

其他报告程序（例如 growl、junit、teamcity 或 coverage）可以通过 plugins 加载。

注意

Karma 中几乎所有其他报告程序（progress 除外）都需要安装额外的库（通过 npm）。

formatError #

类型：函数

默认值：undefined

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

参数

  • msg - 断言错误和堆栈跟踪的一行（对每一行调用）。

返回值：新的错误消息行。

描述：格式化断言错误和堆栈跟踪。对于删除供应商和编译的源代码很有用。返回空行 '' 以将其删除。

CLI 选项应为导出格式函数的文件的路径。这可以是模块根目录中导出的函数，也可以是名为 formatError 的导出。

pingTimeout #

类型 数字

默认值 5000

描述 Socket.io pingTimeout（以毫秒为单位），https://socketio.node.org.cn/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

描述：响应代理时调用。

有关此内容的详细信息，请参阅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 服务器需要在更改基本 URL 等的代理后面运行时使用。

如果设置，则将定义以下字段，并且可以覆盖它们。

path #

类型：字符串

默认值：'/'

描述：在启动浏览器时将附加到基本 URL，并在浏览器加载的内部 URL 前附加。

port #

类型：数字

默认值：9875

描述：在启动浏览器时将用作端口。

hostname #

类型：字符串

默认值：'localhost'

描述：在启动浏览器时将用作主机名。

protocol #

类型：字符串

默认值：'http:'

描述：在启动浏览器时将用作协议。

urlRoot #

类型：字符串

默认值：'/'

描述：Karma 运行的基本 URL。

Karma 的所有 URL 都会以urlRoot为前缀。当使用代理时，这很有用，因为有时您可能希望代理 Karma 已经占用的 URL。

browserSocketTimeout #

类型：数字

默认值：20000

描述：客户端套接字连接的超时时间（以毫秒为单位）。

此配置表示客户端等待套接字连接的时间。

在不同环境中运行浏览器时，客户端套接字连接可能需要不同的时间。如果 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.

如果看到此错误，您可以尝试增加套接字连接超时时间。