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

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

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

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

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

特とくに条件じょうけん文ぶんを使つかったテンプレートは、多おおくの引数ひきすうをとったり、#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:セクション#条件じょうけん文中ぶんちゅうのセクションをご覧らんください。