Wikipedia:テンプレートのサンドボックスとテストケース

この文書はウィキペディア日本語版のガイドラインです。多くの利用者が基本的に同意しており、従うことが推奨されますが、方針ではありません。必要に応じて編集することは可能ですが、大きな変更を加える場合は、先にノートページで提案してください。

ショートカット:

WP:TESTCASES

テンプレートはメディアウィキのとても強力な機能ですが、経験を積んだ利用者であってさえも、簡単に失敗をしてしまうことがあります。したがって、バグを防ぐために、複雑なテンプレートにはそのサブページとして、試作を行うサンドボックスとその試作品の呼び出しをテストするテストケースが必要です。

この方法が向いているテンプレート

テンプレートは多くのページに呼び出されるものであり、テンプレートの編集で失敗をするとその影響が大きくなります。そのため、大きな変更をする前にサンドボックスでテストをするのがよいでしょう。膨大な数のページに呼び出されているテンプレートは、編集する前に必ずテストしてください。

特に条件文を使ったテンプレートは、多くの引数をとったり、#switch演算子の多くの分岐によって、非常に多彩な出力を生成することができます。このようなテンプレートは、プレビューやサンドボックスだけでは問題がないか確かめることが困難であり、テストケースでいろいろなパターンの出力を試すことが勧められます。さらに、このようなテストケースは表示例の一覧としても役に立ちます。

逆に、関連項目へのリンク一覧であるナビゲーションテンプレートのように、パラメータを受け取らず、どの呼び出し先でも同じ表示がされるものはテストケースを利用する利点が少ないといえるでしょう。

また、テンプレートが呼び出されたページの構成によっては表示に問題が起こることがあります。それを防ぐために、サンドボックスに作成したテンプレートを様々な環境で閲覧して確かめたり、テストケースで他のテンプレートや表、画像などと一緒に表示した結果をテストすることもできます。

サンドボックスとテストケースのサブページの作り方

サブページを作る

テンプレートの名前がTemplate:Xだとすると、サンドボックスの名前はTemplate:X/sandbox、テストケースの名前はTemplate:X/testcasesになります。

テンプレートの解説に、{{Documentation}}が使われていれば、それぞれのサブページへの赤リンクがあるので、そこからサブページを作成することができます。既にこの名前のサブページがあれば、{{Documentation}}を用いてそれらにリンクすることができます。{{Documentation}}が使われていない場合は、改めて使用するか独自にサブページへのリンクを作ってください。

サンドボックスにコードを複製する

サンドボックスにコードを複製します。その際、履歴継承の必要性などGFDLの諸条件を満たす必要があります。つまり、

Template:X/sandboxの末尾に、Template:Xから <noinclude> で囲まれていない部分全体を複製します。要約欄には「[[Template:X]]のxxxx年xx月xx日 xx:xx (UTC) から一部複製」と記入し一旦投稿します。
次のコードを最初の行の先頭に挿入します。<noinclude>と</noinclude>の間には空行があっても構いませんが、</noinclude>の後には空行や空白を入れないでください。
```
<noinclude>{{Template sandbox notice}}</noinclude>
```
必要があればその他の編集を行なった上で投稿します^[1]。

1.と2.とで2回に分けて投稿するのは複製作業と編集作業とを明確に区別するためです。手順の詳細については、Wikipedia:ページの分割と統合#一部転記の手順も参考にしてください。

テストケースを作る

Template:X/testcasesにはいくつかの呼び出しの例 ({{X | .... }}) を作成します。テンプレートの解説文にある場合はそれをコピーしてください。そして、それぞれの例をさらに二つに複製します。さらにそれぞれの例の片方について、XをX/sandboxに置き換えてください。これで、元のテンプレートによる表示と新しいテンプレートによる表示を一つ一つ比較できるようになります。最後に、{{Template test cases notice}}をテストケースのページの先頭に加えてください。周囲に空行を入れても構いません。

最終的に、Template:X/testcasesは、次のようなコードになるはずです：

{{Template test cases notice}}

{{X | .... }}
{{X/sandbox | .... }}

{{Test case}} を利用して省力化することもできます。

サンドボックスとテストケースの使い方

まず、サンドボックスを編集して新しいテンプレートにします。ノートページやローカルのエディタなどで新しいテンプレートを用意してある場合や、既存のテンプレートと全く違うものを作る場合でなければ、サンドボックスを作るときと同じように現在のテンプレートを複製してから、それを編集しましょう。

次にテストケースを表示し、新しいテンプレートが問題なく呼び出されるか確認します。新しい出力と元の出力を比較するには、テストケースに一度に表示されるのを比べる方法だけでなく、タブ・ブラウザを使って、サンドボックスを変更する前にテストケースのサブページを表示し、サンドボックスの変更後にもう一つのタブで表示することで、変更前後のテストケースを比べる方法もあります。

サンドボックスのテンプレートが全てのテストケースで問題ないようでしたら、本物のテンプレートをサンドボックスのものに書き換えます。この際にも履歴継承の必要性などGFDLの諸条件を満たす必要があります。#サンドボックスにコードを複製する際と同様の手順で作業してください。

サンドボックス対応のコードの書き方

サンドボックスとテンプレート本体のページはコードの複製を頻繁に繰り返すことになります。そのため、毎回、サンドボックスに複製するときは{{Template sandbox notice}}を加え、テンプレート本体に複製するときは{{Template sandbox notice}}を除去するというのは、少しばかり手間だと感じるかもしれません

この点は、あらかじめ、テンプレート本体のページをサンドボックス対応にしておけば、面倒な作業は発生しません。

{{Template sandbox notice}}は貼り付けられたサブページ名が「sandbox」でない限り、何も引数を指定していなければ、何も出力しませんから、次のように本体のテンプレート本体のページに書いておけば、テンプレート本体のコードとsandboxのコード全体を相互に複製しても、サンドボックスでだけメッセージが表示されます:

<noinclude>
{{ Template sandbox notice }}
</noinclude><!-- テンプレートの本体コード -->

さらに、(1)テンプレート本体のページではある告知を出し、サンドボックスでは出したくない場合、(2)逆にサンドボックスではある告知を出し、テンプレート本体のページでは出したくない場合、あるいは(3)テンプレート本体のページとサンドボックスで出す告知を使い分けたい場合、次のようなコードを使うことができます^[2]^[3]：

<noinclude>
{{
  #ifeq: {{SUBPAGENAME}} | sandbox
  | <!-- サンドボックスで出す告知 -->{{Template sandbox notice}}
  | <!-- サンドボックス以外で出す告知：{{保護}}、{{複雑なテンプレート}}など -->
}}
</noinclude><!-- テンプレートの本体コード -->

もっとも、同様のテンプレート本体のページとサンドボックスでの使い分けは、{{Template sandbox notice}}の引数を使って、次のようなコードでも実現できます：

<noinclude>
{{
  Template sandbox notice
  | notice-for-sandbox = <!-- サンドボックスで出す告知 -->
  | notice-not-sandbox = <!-- サンドボックス以外で出す告知：{{保護}}、{{複雑なテンプレート}}など -->
}}
</noinclude><!-- テンプレートの本体コード -->

また、テンプレート本体に適用される言語間リンクやカテゴリ（例：Category:ウィキペディアのテンプレート）を、テンプレート説明文書のサブページ（Template:X/doc）<includeonly></includeonly>構文で書いている場合^[3]、サンドボックスにそのコードをそのまま複製すると、サンドボックスのページにも同じ言語間リンクやカテゴリが適用されてしまいます。しかし、次のようなコードを書いてはいけません：

<noinclude>
{{
  #ifeq: {{SUBPAGENAME}} | sandbox
  | 
  | {{Documentation}}
}}
</noinclude>

このように記述した場合、{{Documentation}}で読み込まれた文書の節編集リンクが機能しなくなります^[4]。かわりに、テンプレート説明文書の中でつぎのような条件文を使うことで対処できるので、検討してみてください：

<includeonly>
{{
  #ifeq: {{SUBPAGENAME}} | sandbox
  | 
  |
<!-- ここに、テンプレート本体に適用する言語間リンクやカテゴリを書く。-->
}}
</includeonly>

テストケース対応のコードの書き方

前節ではテンプレート自体に適用するカテゴリについて述べましたが、テンプレートの中には、そのテンプレートを貼り付けたページに一定のカテゴリ（例：Category:スタブ）を適用するものがあります。そのようなテンプレートをテストケースに使用すると、テストケースもそのカテゴリに含まれてしまいます。

これを避けるためには、テンプレートを貼り付けたページに適用するカテゴリを、テンプレートの中の次のようなコードで記述することができます:

<includeonly>{{
  #ifeq: {{NAMESPACE}} | {{ns:0}}
  | <!-- テンプレートを貼り付けたページに適用するカテゴリをここに書く -->
}}</includeonly>

このコードは、標準名前空間のページ（つまり普通の記事）に貼り付けられたときのみ、そのページをカテゴリに含ませます。また、このコードを使えば、ノートページでテンプレートについて説明する場合など、そのテンプレートを標準名前空間以外の場所で使うときに、そのページをカテゴリに含ませないという効果もあります。ノートページで使用するためのテンプレートなどの場合は、{{ns:0}}の部分を、適当なマジックワードに代えてください。

逆に、どの名前空間でも使用したい、つまり貼り付けたページがどの名前空間であってもカテゴリに含ませたいとき、それでもなおピンポイントでテストケースでだけはカテゴリの適用を避けたい場合は、次のようなコードを使用できます:

<includeonly>{{
  #ifeq: {{SUBPAGENAME}} | testcase
  |
  | <!-- テンプレートを貼り付けたページに適用するカテゴリをここに書く -->
}}</includeonly>

<includeonly>{{
  #ifeq: {{FULLPAGENAME}} | {{ns:10}}:X/testcase
  |
  | <!-- テンプレートを貼り付けたページに適用するカテゴリをここに書く -->
}}</includeonly>

もちろん、他の方法もありえますし、引数やより複雑な条件文を使ってより高度な動作を行わせることもできます。

実例

Template:Ambox-mini
- Template:Ambox-mini/sandbox
- Template:Ambox-mini/testcases

脚注

^ テンプレートの始めに表があると、それが正しく表示されないことがあります。その場合は</noinclude>の前に改行を入力してください。
^ テンプレートの説明文（Template:X/doc）がある場合には、テンプレート本体の告知は<includeonly></includeonly>構文を用いて説明文のサブページに書いた方が便利です。
^ ^a ^b テンプレート本体に適用されるものを<includeonly></includeonly>構文を用いて説明文のサブページに書く方法には、テンプレートの編集が保護されている場合に、テンプレート本体に適用される言語間リンクやカテゴリを変更できるようにするなどの効果があります。
^ 呼び出した文書が条件文中にあることが原因です。詳しくはHelp:セクション#条件文中のセクションをご覧ください。