= cutter / Cutter / Cutterのマニュアル

== 名前

cutter - C言語・C++言語用のxUnit系テスティングフレームワーク

== 書式

(({cutter})) [((*オプション...*))] ((*テストディレクトリ*))

(({cutter})) --mode=analyze [((*オプション ...*))] ((*ログディレクトリ*))

== 説明

CutterはC言語・C++言語用のxUnit系単体テスト（ユニットテスト）
フレームワークです。Cutterはプログラマに2つの重要なインターフェ
イスを提供します。

  (1) 簡単にテストが書けるAPI
  (2) 簡単にデバッグできるユーザインターフェイス

Cutterはプログラマが新しいテストを書くこと、すでにあるテスト
を実行すること、実行したテストからフィードバックを得ることを
支援します。

((*テストディレクトリ*))にはtest_*.soがあるディレクトリを指
定します。Cutterはtest_*.soは再帰的に検索します。

((*ログディレクトリ*))にはCutterのログファイルがあるディレク
トリを指定します。Cutterは--stream-directoryオプションがして
いされるとテスト結果をログファイルに出力します。

== オプション

: --version

   バージョンを表示して終了します。

: --log-level=LEVEL

   ログレベルをLEVELに設定します。

   LEVELは「error|warning」というように「|」で区切って指定できます。

   「+trace|+info」というようにレベルの前に「+」をつけるとデフォルトのレベルに
   指定したレベルを追加できます。

   「-error|-warning」というようにレベルの前に「-」をつけるとデフォルト
   のレベルから指定したレベルを取り除けます。

   指定できるレベルは以下の通りです。

   * default: 「critical|error|warning|message」と同じ。
   * none: なにも出力しない。
   * critical: 致命的な問題のみ出力。
   * error: エラーのみ出力。
   * warning: 警告のみ出力。
   * message: 通常のメッセージのみ出力。
   * info: 付加情報のみ出力。
   * debug: デバッグ情報のみ出力。
   * traces: トレース情報のみ出力。
   * all: すべての情報を出力。

   デフォルトは「default」です。

: --mode=[test|analyze]

   実行モードを指定します。testモードのときはテストを実行し
   ます。analyzeモードのときはテスト結果を解析します。

   デフォルトはtestです。

: -s DIRECTORY, --source-directory=DIRECTORY

   テストが失敗した場合にファイル名の前にDIRECTORYを付加しま
   す。Cutterの出力からテストが失敗した箇所にジャンプするツー
   ル（Emacsなど）と連携するための機能です。

: -t TEST_CASE_NAME, --test-case=TEST_CASE_NAME

   TEST_CASE_NAMEにマッチしたテストケースを実行します。もし、
   TEST_CASE_NAMEが"/"で囲まれていた場合は（例: /test_/）正
   規表現として扱います。

   このオプションは複数回指定できます。その場合は、どれかの
   TEST_CASE_NAMEにマッチしたテストケースを実行します。（OR）

: -n TEST_NAME, --name=TEST_NAME

   TEST_NAMEにマッチしたテストを実行します。もし、TEST_NAME
   が"/"で囲まれていた場合は（例: /test_/）正規表現として扱
   います。

   このオプションは複数回指定できます。その場合は、どれかの
   TEST_NAMEにマッチしたテストケースを実行します。（OR）

: -m, --multi-thread

   各テストケースを新しいスレッドで実行します。

   デフォルトでは無効です。

: --max-threads=MAX_THREADS

   最大MAX_THREADSスレッドを同時に動かしてテストケースと繰り
   返しテストを実行します。-1を指定すると最大同時スレッド数
   を制限しません。

   デフォルトは最大10スレッドです。

: --disable-signal-handling

   C-cでのテスト途中終了や、SEGV時のバックトレース取得などを
   行うシグナル処理機能を無効にします。シグナルを用いてるラ
   イブラリをテストする場合はこの機能が障害になることがあり
   ます。その場合はこのオプションでCutterのシグナル処理機能
   を無効にしてください。

   デフォルトでは有効です。

: --test-case-order=[none|name|name-desc]

   各テストケースの実行順を並び替えます。

   noneを指定すると並び替えません。nameを指定するとテストケー
   ス名で昇順に並び替えます。name-descを指定するとテストケー
   ス名で降順に並び替えます。

   デフォルトはnoneです。

: --exclude-file=FILE

   テストを集めるときにFILEを読み込みません。

: --exclude-directory=DIRECTORY

   DIRECTORY以下にあるテストを検索しません。

: --fatal-failures

   失敗を致命的な問題として扱います。つまり、表明に失敗する
   とテストの実行を中断します。

   デフォルトでは無効です。

: --keep-opening-modules

   ロードしたモジュールを開いたままにします。シンボルを解決
   できるようになるため、デバッグ時に便利です。

   デフォルトでは無効です。

: --enable-convenience-attribute-definition

   便利ですが、危険でもある、
   "#{属性名}_#{テスト名 - 'test_'プリフィックス}"属性設定関
   数を有効にします。

   デフォルトでは無効です。

: --stop-before-test

   テスト関数を実行する直前にブレークポイントを設定します。
   デバッガ上でcutterを実行し、ステップインすれば、簡単にテ
   スト関数に入ることができます。

   デフォルトでは無効です。

: -u=[console|gtk], --ui=[console|gtk]

   UIを指定します。

   デフォルトはコンソールUIです。

: -v[s|silent|n|normal|v|verbose], --verbose=[s|silent|n|normal|v|verbose]

   出力の詳細さを指定します。

   このオプションはコンソールUIを使用する場合だけ有効です。

: -c[yes|true|no|false|auto], --color=[yes|true|no|false|auto]

   yesまたはtrueが指定された場合はCutterはエスケープシーケン
   スで色付けして出力します。noまたはfalseが指定された場合は
   色付けしません。autoあるいは値が省略された時は、可能なら
   色付けをします。

   このオプションはコンソールUIを使用する場合だけ有効です。

: --pdf-report=FILE

   FILEにPDF形式でテスト結果を出力します。

: --xml-report=FILE

   FILEにXML形式でテスト結果を出力します。

: --stream=[xml]

   ストリームバックエンドを指定します。ストリームバックエン
   ドはテスト結果を配信します。

   現在はXMLストリームバックエンドがあります。

: --stream-fd=FILE_DESCRIPTOR

   出力ファイルディスクリプタを指定します。XMLストリームバッ
   クエンドはFILE_DESCRIPTORに配信します。

   このオプションはXMLストリームバックエンドを使用する場合だ
   け有効です。

: --stream-directory=DIRECTORY

   出力ディレクトリを指定します。XMLストリームバックエンドは
   DIRECTORY以下にファイルを作成し、そのファイルに配信します。

   このオプションはXMLストリームバックエンドを使用する場合だ
   け有効です。

: -?, --help

   UIやテスト結果レポート機能に依存しないオプションを表示し
   ます。

: --help-stream

   ストリーム関連のオプションを表示します。

: --help-report

   レポート関連のオプションを表示します。

: --help-ui

   UI関連のオプションを表示します。

: --help-all

   すべてのオプションを表示します。

== 終了ステータス

すべてのテストがパスすると0で、そうでない場合は0以外になりま
す。テスト結果の「省略」と「通知」は失敗として扱いません。

== ファイル

: /usr/local/share/doc/cutter/ja/

   リファレンスマニュアルやチュートリアルなどのCutterのドキュ
   メントがあります。

== 例

以下の例では、cutterはtest/ディレクトリ以下のテストを実行し、
テストの進行状況を詳細に表示します。

  % cutter -v v test/

以下の例では、テスト結果がlogs/ディレクトリ以下に保存されま
す。

  % cutter --stream=xml --stream-directory=logs/ test/

== 関連項目

GLibのリファレンスマニュアル。
