[15日目] 不具合を発見したときのテストレポートの心得

Tweet

こんばんは。稲垣です。組み込みプログラム担当として、CEREVO CAM live!やLiveShellシリーズなどのライブ配信系製品をずっと作っています。

今回は製品やサービスを開発するなかで避けて通れないテストレポートとかバグトラッカーのチケットとかを書くときのテクニックを社内向けにまとめた内容をTechBlogに持ってきました。題して「テストレポートの心得」。前半がテクニック本体で、後半が今回ブログ向けに追加した効能とか背景の解説となっています。それではどうぞ。

テストレポートの心得

テストの結果、不具合を見つけたら再現方法を報告しましょう。 この心得を読めばきっと突っ込まれないレポートができるはず。

標題と概要の心得

まず、どんな不具合を起こすかを端的に書いて標題にします。

標題だけで書ききれない場合は概要を書きましょう。1つの手順で複数の不具合が起きる場合、箇条書きにしましょう。

どこが不具合なのかはっきりさせて書くためには、どのような挙動に直すべきかを考えて、対比させてみるとよいかも知れません。

再現方法の心得

次に再現方法を記録します。再現方法は、読んだ人が同じように操作して再現できるように記録しなければいけません。

いろいろな解釈ができる書き方は再現方法の書き方としてよくありません。同じことをするのに複数の方法が考えられる場合、どの方法をとったか明記しましょう。それはつまり、何をどのように操作したか、何をどんな方法で観察したのかを説明するということです。操作だけでなく観察の方法もしばしば複数あります。

再現方法は事実の記録として書くべきで、全て過去形で「何々した」という記述の羅列になるはずです。タイミングが重要である場合 (タイミングによって再現しなかったとか)、「すぐに何々した」とか「何分間待ってから何々した」などをきちんと記録しましょう。再現方法を書いたら、その方法で本当に再現するか試してみましょう (ただし正常な動作を続けられなくなるような重大な不具合は早めに報告した方がよいでしょう)。

何回実験して、何回不具合が再現したかを記録しましょう。1回試して1回再現したのと、10回試して10回再現したのとは違います。

よくない記録の例

「動かなかった」
「何々しなかった」

期待したとおりに動かなかったことは、不具合として報告されている時点で自明です。このような記述から読み取れるのは、あなたの願望と、それがそのとおりにならなかったということだけです。

実験の結果には「どうなったか」を記録するべきです。「どうならなかったか」は書かないとそのほかの事象とまぎらわしい場合だけ記録すれば十分です。たとえば天気の記録を付けるのに、「雨は降らなかった」とだけ記録することがあるでしょうか? 必ず「快晴」「曇り」「雪」などと実際の天気を記録するはずです。

考察の心得

最後に、なにか考察を書きたければ書いてもかまいません。最後に書くのは、事実の記録である再現方法とあなたの推測を区別するためです。事実と想像を混同してはいけません。

不具合の原因についてなにか推測したのなら、それを検証するための実験を考えた方がよいでしょう。

FAQ

これは本当に問題なのか? と思ったら

「俺がルールだ」と思っていただければ結構です。これっておかしいんじゃないの? と思う部分はきっと他のユーザもそう思うでしょう。そういうところには直すかマニュアルやFAQでフォローするかの対策をすることになります。

再現条件をどこまで絞り込んでチケットにするか

必要十分条件を最初から見つける必要はありません。再現方法には事実だけ記せばよいのですから、十分条件が分かっていればよいのです。たとえば10分しか待つ必要がないことが後から明らかになるとしても、30分待って再現したのならまずはそう書けばよいのです。

解説

心得編はいかがでしたか。基本的には大学なんかで実験レポートを書くときに教えられることだったんじゃないかと思いますが……。ここからは背景の事情とかの解説編です。

複数の方法

LiveShellみたいな製品を作っていると、たとえばある設定を変える操作がDashboardからでもできるし、本体のキーを押してもできるということがあります。そして片方でしか問題が起きないことがあったりします (大抵両方で起きます)。本体のUIも頑張って作ってますから使ってください。

観察の方法が複数あるというのも同じ事情です。たとえばビットレートの表示はDashboardにもあるし本体にもあります。これがDashboardの表示だけおかしいとなると、web側の問題である可能性が高いので組み込み担当はホッとします。どこが問題か分からない書き方をされると余計なところにまで無用な不安が拡がります。

過去形で

過去形で書くのは科学的に大変重要なことです。現在形で書くとどうなるか。「フリーズする」。今まさに目の前でフリーズするってときだけは適切な言葉です。しかし何もないのにフリーズするフリーズすると言うと、それは公理や定理の書き方です。つまりそれが真実であると主張していることになります。「お前のプログラムはフリーズする……それが永遠の真実、世界の理 (コトワリ)、変えられない運命なのだ」。呪いですね。プログラマに恨みでもあるんでしょうか。

これが過去形で書いてあると、途端に過去の一個の事象に格下げとなります。あのときはフリーズした。でも将来は分からない。他の人が操作したら違う結果になるかも知れない (ヒューマンエラーだ!)。一挙に謙虚になりました。美徳ですね。

「『フリーズした』なら使ってもいい!」

何回実験したか記録する

サンプリングというのは回数を増やすほど信頼性が高くなります。1回試して1回起きただけだと、追試してみたら本当に1回しか再現しないこともありますし、忙しいときはそんな再現するのかしないのか分からない事象にはなかなか手が出せません。全部の個体で起きるとも限りませんしね。これが10回試して10回再現したとか百発百中とかになると、自分の個体でも出荷した個体でもそこでもここでも再現する可能性が高まってきます。ヤバい。

よくない記録

「動きません」。ありがちです。エラーメッセージくらいは報告してほしいものです。エラーメッセージの目的の半分は報告してもらうことにあります。ちなみに残りの半分は「やさしさ」です。解決の糸口になりそうなことも書いておきました。できれば自力でなんとか。

「フリーズした」。「画面が動かなくなった」と同義です。「○○しなかった」の報告は情報量が少なくてツッコミ返す必要があるから手間なんですよね……本当に何をしても動かなかったの? 何をしたのか列挙してみて? なんだACアダプタの抜き差しを試してないじゃあないか。ホラ、インジケータが変わった。フリーズはしてないでしょ。使いものにならないことには変わりありません。でもネチっこく絡まれます。

最後に

「過去形で書け」とか大学で実験レポートを書くときに必ず指導されることで、リアルに「あっこれゼミでやったやつだ!」と思える内容だったかも知れません。社会人の方々には昔を懐かしみつつ、一つでも「あれはそういうことだったのか」と納得していただけたら幸いです。まだ学生の皆さんはしっかり勉強して、勉強したことが役立つ仕事ができるように頑張ってください。この心得があなたの心に残って、素敵なレポートライフの一助となることを願っています。

Happy Hacking!