KDOC 19: ertを読む

ertはEmacs組み込みのテストフレームワークである。

Tasks

TODO shouldはどうやって検証しているか

ertで定義された関数では、shouldで検証している。名前的にertに含まれないように見えるが、ertファイルで定義されている。 

https://github.com/kd-collective/emacs/blob/30cf1f34c583d6ed16bdc5b9578370f30c95fe1b/lisp/emacs-lisp/ert.el#L378-L379

(cl-defmacro should (form) “Evaluate FORM. If it returns nil, abort the current test as failed.

  • should
    • ert–expand-should
      • ert–expand-should1

TODO 失敗時の値の比較表示はどうやっているか

expectedとresultの値を表示して、どこがおかしいのかを表示してくれる。

TODO 統計記録をどうやっているか

実行テストは選択できる。実行したテストについて、成功数や時間を表示する。

TODO cl-defmacro と defmacro の違い

使い分けているように見えるが、何が違うのかわからない。

TODO run-test-at-pointを作ってみる

リストから選ぶのが面倒なので、実行できるようにする。

Memo

ertの全体像

テストフレームワークの全体像をソースコードから把握する。

  • テスト定義
  • マッチャ関数
  • テスト実行
  • エラー時の値表示
  • テストセレクタ
  • テストのサマリー表示
    • 成功数
    • 失敗数
    • 開始時間
  • バッチ実行
  • JUnit形式出力
  • 実行テスト登録・削除
  • プログレスバー
  • モードライン表示
  • 成功時・失敗時のface設定
  • ert-results-mode の各種機能・キーバインド

デバッグ情報を定義する

defmacroにメタ情報を定義するときは、declareを使う。 

https://github.com/kd-collective/emacs/blob/30cf1f34c583d6ed16bdc5b9578370f30c95fe1b/lisp/emacs-lisp/ert.el#L215-L217

(declare (debug (&define [&name “test@” symbolp] sexp [&optional stringp] [&rest keywordp sexp] def-body))

エラーを定義する

(define-error 'my-failed "failed")

プロパティにmy-failedを登録する。

UI用の関数

  • insert-text-button
    • ボタンを追加する

deftestを実行するとどうなるか

  • ert-deftest 構造体に必要な情報を収集
    • ert-set-test make-ert-testで作った構造体でシンボルを登録する
      • make-ert-test テスト実行に必要なスロットを用意したオブジェクトを作る。test name, body, doc, file name …

ということで、テスト構造体がシンボルとして登録される、という感じか。単純。 

https://github.com/kd-collective/emacs/blob/30cf1f34c583d6ed16bdc5b9578370f30c95fe1b/lisp/emacs-lisp/ert.el#L191

(cl-defmacro ert-deftest (name () &body docstring-keys-and-body) 

https://github.com/kd-collective/emacs/blob/30cf1f34c583d6ed16bdc5b9578370f30c95fe1b/lisp/emacs-lisp/ert.el#L140

(defun ert-set-test (symbol definition)

実行テストリストをどうやって表示しているか

実行できる実行の一覧から選んで実行することになる。このリストはどうやって表示しているのだろうか。

  • obarray シンボルテーブル
  • seq-filter リストをフィルタする
  • obarray の中から、ert-test に割り当てられたものをフィルタリングして、ert-deftestで定義されたテストオブジェクトを取り出している
  • 取り出したリストをcompleting-readに渡して選択肢表示する

テストを実行するとき何が起きているか

  • ert-run-tests-interactively 実行可能なテストのリストを選択、バッファ表示、実行
    • listenerはevent-typeを受け取る無名関数
    • ert-run-tests 特定したテストを実行する
      • 結果を取得し、変数most-recent-resultに保存する
https://github.com/kd-collective/emacs/blob/30cf1f34c583d6ed16bdc5b9578370f30c95fe1b/lisp/emacs-lisp/ert.el#L2254

(defun ert-run-tests-interactively (selector) 

(ert-run-tests-interactively 'cl-remove-if-not-test)
  • ert-run-tests-interactively
    • テストそのものというより、ユーザ入力とバッファで見せる部分が多くを占める
    • interactive関数によって、M-xで呼んだときにはcompletionの値が入る
    • この引数の名前はselectorという名前がついている
    • listerはどういう意味か。関数なのは確か
      • event-typeによって処理が変わる関数
      • run-startedのときは準備バッファを表示する
      • run-endedのとき成功してたら統計バッファを表示する
      • test-startedのとき
        • ewocって何だ
          • ewoc関係の関数は組み込みで入っている
      • test-endedのときは統計バッファを更新する
  • ert-run-tests
    • ert-run-or-rerun-test
    • ert-run-test
      • ert–run-test-internal
        • デバッグ関連の情報を付加する