パブリック API

ほとんどの場合、Karmaはコマンドラインから直接使用します。ただし、NodeモジュールからプログラムでKarmaを呼び出すこともできます。これがパブリックAPIです。

karma.Server(options, [callback=process.exit]) #

constructor #

  • **戻り値:** Server インスタンス。

使用方法 #

require('karma').Server の 'S'は大文字であることに注意してください。

非推奨の動作 #

以下の方法はまだ動作しますが、その動作は非推奨であり、将来のメジャーバージョンで変更される予定です。

var Server = require('karma').Server
var karmaConfig = {port: 9876}
var server = new Server(karmaConfig, function(exitCode) {
  console.log('Karma has exited with ' + exitCode)
  process.exit(exitCode)
})
新しい動作 #
const karma = require('karma')
const parseConfig = karma.config.parseConfig
const Server = karma.Server

parseConfig(
  null,
  { port: 9876 },
  { promiseConfig: true, throwErrors: true }
).then(
  (karmaConfig) => {
    const server = new Server(karmaConfig, function doneCallback(exitCode) {
      console.log('Karma has exited with ' + exitCode)
      process.exit(exitCode)
    })
  },
  (rejectReason) => { /* respond to the rejection reason error */ }
);

server.start() #

karma start と同等です。

server.start()

server.refreshFiles() #

ファイルリストの更新をトリガーします。Promiseを返します。

server.refreshFiles()

server.refreshFile(path) #

ファイルの更新をトリガーします。Promiseを返します。

server.refreshFile('src/js/module-dep.js')

イベント #

server オブジェクトは EventEmitter です。次のようにイベントをリッスンすることができます。

server.on('browser_register', function (browser) {
  console.log('A new browser was registered')
})

listening #

引数

  • port: ポート番号

指定されたポートで接続の受け入れを開始します。

browser_register #

引数

  • browser: ブラウザインスタンス

新しいブラウザが開かれましたが、まだ準備ができていません。

browser_error #

引数

  • browser: ブラウザインスタンス
  • error: 発生したエラー

このブラウザインスタンスでエラーが発生しました。

browser_start #

引数

  • browser: ブラウザインスタンス
  • info: 実行に関する詳細

このブラウザでテストの実行が開始されます。

browser_complete #

引数

  • browser: ブラウザインスタンス
  • result: テスト結果

このブラウザでテストの実行が完了しました。

browsers_change #

引数

  • browsers: ブラウザインスタンスのコレクション

ブラウザのリストが変更されました。

browsers_ready #

すべてのブラウザが実行準備完了です。

run_start #

引数

  • browsers: テストが実行されるブラウザインスタンスのコレクション

テストの実行が開始されます。

run_complete #

引数

  • browsers: ブラウザインスタンスのコレクション
  • results: 結果のリスト

このイベントは、テスト実行に属するすべてのブラウザが完了するたびにトリガーされます。たとえば、3つのブラウザで実行する場合、`run_complete`の前に3つの`browser_complete`イベントが発生することが予期されます。

karma.runner #

runner.run(options, [callback=process.exit]) #

  • **戻り値:** EventEmitter

karma run と同等です。

使用方法 #

非推奨の動作 #

以下の方法はまだ動作しますが、その動作は非推奨であり、将来のメジャーバージョンで変更される予定です。

var runner = require('karma').runner
runner.run({port: 9876}, function(exitCode) {
  console.log('Karma has exited with ' + exitCode)
  process.exit(exitCode)
})
新しい動作 #
const karma = require('karma')

karma.config.parseConfig(
  null,
  { port: 9876 },
  { promiseConfig: true, throwErrors: true }
).then(
  (karmaConfig) => {
    karma.runner.run(karmaConfig, function doneCallback(exitCode, possibleErrorCode) {
      console.log('Karma has exited with ' + exitCode)
      process.exit(exitCode)
    })
  },
  (rejectReason) => { /* respond to the rejection reason error */ }
);

callback 引数 #

コールバックは、最初の引数として終了コードを受け取ります。

エラーが発生した場合、エラーコードはエラーコールバックの2番目のパラメータとして提供されます。

runner イベント #

runner.run() は、レポーター出力を `Buffer` オブジェクトとして渡す `progress` イベントを発行する `EventEmitter` を返します。

そのイベントをリッスンして、レポーター出力をコンソールに出力できます。

runner.run({port: 9876}).on('progress', function(data) {
  process.stdout.write(data)
})

karma.stopper #

stopper.stop(options, [callback=process.exit]) #

この関数は、実行中のサーバーに停止を通知します。 karma stop と同等です。

使用方法 #

非推奨の動作 #

以下の方法はまだ動作しますが、その動作は非推奨であり、将来のメジャーバージョンで変更される予定です。

var stopper = require('karma').stopper
stopper.stop({port: 9876}, function(exitCode) {
  if (exitCode === 0) {
    console.log('Server stop as initiated')
  }
  process.exit(exitCode)
})
新しい動作 #
const karma = require('karma')

karma.config.parseConfig(
  null,
  { port: 9876 },
  { promiseConfig: true, throwErrors: true }
).then(
  (karmaConfig) => {
    karma.stopper.stop(karmaConfig, function doneCallback(exitCode, possibleErrorCode) {
      if (exitCode === 0) {
        console.log('Server stop as initiated')
      }
      process.exit(exitCode)
    })
  },
  (rejectReason) => { /* respond to the rejection reason error */ }
);

callback 引数 #

コールバックは、最初の引数として終了コードを受け取ります。

エラーが発生した場合、エラーコードはエラーコールバックの2番目のパラメータとして提供されます。

karma.config #

config.parseConfig([configFilePath], [cliOptions], [parseOptions]) #

この関数は、指定された設定ファイルをロードし、設定済みの設定オブジェクトを返します。これは、Karmaを別のツールに統合し、Karmaのデフォルトを尊重しながらKarma設定をロードしたい場合に役立ちます。

使用方法 #

非推奨の動作 #

以下の方法はまだ動作しますが、その動作は非推奨であり、将来のメジャーバージョンで変更される予定です。

const cfg = require('karma').config;
const path = require('path');
// Read karma.conf.js, but override port with 1337
const karmaConfig = cfg.parseConfig(
  path.resolve('./karma.conf.js'),
  { port: 1337 }
);

将来の新しい動作では、プロセスを終了する代わりに例外をスローし、非同期設定ファイルはPromiseを使用してサポートされます。

新しい動作 #
const cfg = require('karma').config;
const path = require('path');
// Read karma.conf.js, but override port with 1337
cfg.parseConfig(
  path.resolve('./karma.conf.js'),
  { port: 1337 },
  { promiseConfig: true, throwErrors: true }
).then(
  (karmaConfig) => { /* use the config with the public API */ },
  (rejectReason) => { /* respond to the rejection reason error */ }
);

configFilePath 引数 #

  • **タイプ:** String | null | undefined
  • **デフォルト値:** undefined

設定ファイルを指すファイルシステムパスを表す文字列。設定ファイルのデフォルトエクスポートは、Karma設定オプションを設定するために使用される関数です。この関数には、最初の引数として `Config` クラスのインスタンスが渡されます。このオプションが指定されていない場合、`cliOptions` 引数によって提供されるオプションのみが設定されます。

  • JavaScriptはCommonJSモジュールを使用する必要があります。
  • ECMAScriptモジュールは、JavaScriptを使用する場合、Karmaでは現在サポートされていません。
    • TypeScriptなどの他の形式は、ECMAScriptモジュールをサポートする場合があります。

cliOptions 引数 #

  • **タイプ:** Object | null | undefined
  • **デフォルト値:** undefined

設定ファイルで設定されたオプションよりも優先される値を持つオブジェクト。設定ファイルによってエクスポートされた関数に渡される設定オブジェクトには、これらのオプションが既に適用されています。設定ファイルがこれらのオプションに加えた変更は、最終的な設定では事実上無視されます。

設定ファイルと同じオプションをすべてサポートし、同じ `config.set()` メソッドを使用して適用されます。

この引数の予期されるソースは解析されたコマンドラインオプションですが、プログラムによるユーザーはこのオブジェクトを構築したり、完全に省略したりできます。

parseOptions 引数 #

  • **タイプ:** Object | null | undefined
  • **デフォルト値:** undefined

`parseOptions` は、解析をさらに制御し、新しい動作や機能へのオプトインアクセスを可能にする設定オプションであるプロパティを持つオブジェクトです。

これらのオプションは、設定ファイルとオブジェクトの解析にのみ関連し、Karma自体の設定には関連しません。

parseOptions.promiseConfig オプション #
  • **タイプ:** Boolean
  • **デフォルト値:** false

`parseOptions.promiseConfig === true` の場合、`parseConfig` は設定オブジェクトの代わりにPromiseを返します。

このオプションが `true` の場合、設定ファイルによってエクスポートされた関数はPromiseを返す場合があります。そのPromiseの解決は、すべての非同期アクティビティが完了したことを示します。内部的には、解決/履行された値は無視されます。同期使用と同様に、設定オブジェクトに対するすべての変更は `config.set()` メソッドを使用して行う必要があります。

設定ファイルによってエクスポートされた関数がPromiseを返さない場合、解析は完了し、すぐに履行されたPromiseが返されます。

設定ファイルによってエクスポートされた関数がPromiseを返すかどうかに関係なく、`parseConfig()` によって返されるPromiseは、解析された設定オブジェクト（`Config` クラスのインスタンス）を値として解決します。

ほとんどの場合、`parseOptions.throwErrors = true` も設定する必要があります。これにより、プロセスが終了しなくなり、エラーによってPromiseが拒否されるようになります。

parseOptions.throwErrors オプション #
  • **タイプ:** Boolean
  • **デフォルト値:** false

以前は、`parseConfig()` は重大な障害が発生した場合に `process.exit(exitCode)` を呼び出していました。これは、Node.jsプロセスが終了する前に、独自のコードが障害に対応する方法がないことを意味していました。

`parseOptions.throwErrors = true` を渡すことで、`parseConfig()` はプロセスの終了を無効にします。

同期使用の場合、プロセスを終了する代わりに例外がスローされます。その後、コードは例外をキャッチし、必要な方法で応答できます。

非同期API（`parseOptions.promiseConfig = true`）が使用されている場合、`parseOptions.throwErrors = true` により、プロセスを終了する代わりにPromiseが拒否されるようになります。

karma.constants #

constants.VERSION #

Karmaの現在のバージョン

constants.DEFAULT_PORT #

Karmaサーバーに使用されるデフォルトポート

constants.DEFAULT_HOSTNAME #

Karmaサーバーに使用されるデフォルトのホスト名

constants.DEFAULT_LISTEN_ADDR #

Karmaサーバーがリッスンするために使用するデフォルトアドレス

constants.LOG_DISABLE #

ログを無効にするための値

constants.LOG_ERROR #

ログレベル `error` の値

constants.LOG_WARN #

ログレベル `warn` の値

constants.LOG_INFO #

ログレベル `info` の値

constants.LOG_DEBUG #

ログレベル `debug` の値

constants.LOG_PRIORITIES #

ログレベルの配列（降順）：`LOG_DISABLE`、`LOG_ERROR`、`LOG_WARN`、`LOG_INFO`、`LOG_DEBUG`

constants.COLOR_PATTERN #

ログ出力のデフォルトカラーパターンです。

constants.NO_COLOR_PATTERN #

カラー出力を行わない場合のログ出力のデフォルトパターンです。

constants.CONSOLE_APPENDER #

デフォルトのコンソールアペンダーです。

constants.EXIT_CODE #

終了コードです。