テストを書く

テストを書いていただきありがとうございます！テストは優れています！テストにより、何も壊さずにコードベースを向上させることができます。また、この方法により、Prismのアップグレードができる限り簡単に行えるようになります。

tests/languages/${language}に格納されているテストディレクトリに新しいテストケースファイル（.testファイル拡張子を使用）を作成することで、新しいテストを追加できます。

言語ディレクトリ

すべてのテストはtests/languagesディレクトリのディレクトリに分類されています。各ディレクトリ名は、現在テストしている言語をエンコードします。

すべての言語名は、components.jsonの定義の名前と一致している必要があります。

例1：単独で言語をテストする（通常の使用ケース）

テストファイルを単にテストする言語のディレクトリに配置します。

そのため、CSSをテストする場合は、CSSのみをテストするには/tests/languages/cssにテストファイルを入れます。このディレクトリにテストケースを作成すると、テストランナーはすべての必要な言語定義を含めたcss言語定義が正しくロードされていることを確認します。

例2：言語インジェクションをテストする

言語インジェクションをテストする場合は、通常、2つ以上の言語をロードする必要があります。1つの言語はテストされている「メイン」言語で、他のすべての言語はそれにインジェクトされます。

+記号を使用してそれらを分離することで、複数の言語を定義する必要があります：markup+php。

言語は順番にロードされ、最初にmarkup（+依存関係）がロードされ、その後php（+依存関係）がロードされます。テストローダーは、どの言語も一度にロードされることがないことを保証します（たとえば、2つの言語に同じ依存関係がある場合）。

デフォルトでは、最後の言語がメイン言語です：php+markupは、markupをメイン言語として持つことになります。これは、次のコードブロックにコードを配置するのと同じです

...
<pre><code class="language-markup">
	<!-- your code here -->
</code><pre>
...

与えられた順番で言語をロードする必要があるが、最後の言語をメイン言語として使用したくない場合は、感嘆符を使用してメイン言語をマークできます：php!+markup。これにより、phpがメイン言語として使用されます。（メイン言語は1つしか定義できません。テストランナーは、メイン言語が複数のディレクトリにある場合はすべてのテストを失敗させます。）

注：複数の言語をロードすることで、統合テストを実行できます（2つ以上の言語を一緒にロードしても何も壊れないことを確認できます）。

テストケースファイルを作成する

まず、テストする言語ディレクトリに新しいファイルを作成する必要があります。

テストケースに適切な名前を使用します。次の規則のいずれかのケースを使用してください

issue{issueid}：githubの問題IDを参照します（例：issue588.test）。
{featurename}_feature：1つのファイル内の1つの機能にすべてのテストをグループ化します（例：string_interpolation_feature.test）。
{language}_inclusion：一方の言語に別の言語を含めることをテストします（例：markup!+css/css_inclusion.testは、markupへのCSSのインクルージョンをテストします）。

接頭辞としてすべての規則を使用できるので、string_interpolation_feature_inline.test は可能です。ただし、テストケースファイルの適切な名前を考えるために数分時間を費やしてください。コードはコンピュータだけでなく、開発者仲間のためにも記述するのです。

テストの記述

テストケースファイルは、行の頭に 10 個以上のダッシュ (-) を区切りとして置いた 2 つまたは 3 つのセクションで構成されます。セクションは以下のとおりです。

言語スニペット。Prism を使用してトークン化したいコードです。(必須)
期待される簡略化されたトークンストリーム。JSON である必要があります。(オプション)
テストランナーは、存在しない場合はこれを自動的に挿入します。挿入されたトークンストリームが期待どおりであることを注意深く確認してください。
JSON には存在するものの誤っていた場合にテストケースが失敗したら、--update フラグを使用して上書きできます。
テストケースを説明する簡潔なコメント。(オプション)

以下に例を示します。

var a = 5;

----------------------------------------------------

[
	["keyword", "var"],
	" a ",
	["operator", "="],
	["number", "5"],
	["punctuation", ";"]
]

----------------------------------------------------

This is a comment explaining this test case.

テストを簡単にかける方法

1 つまたは複数の新しいテストケースを作成する簡単な方法は次のとおりです。

新しいテストケースファイルを作成します。tests/languages/{language}/{test-case}.test
テストしたいコードを挿入します (それ以上は不要です)。
テストケースの数を問わず、最初の 2 つのステップを繰り返します。
npm run test:languagesを実行します。
完了です。

既存のテストケースファイルの更新も簡単です!

npm run test:languages -- --updateを実行します。
完了です。

これは、テストランナーにテストコードの実際のトークンストリームを期待されるトークンストリームとして挿入させることによって機能します。挿入されたトークンストリームが実際に自分の期待どおりであることを注意深く確認してください。そうでなければテストの意味がありません!

テストの更新

言語を作成および変更すると、そのテストファイルを更新して言語を適切にテストする必要があります。テストファイルの更新という面倒な作業は、次のコマンドを使用して自動化できます。

npm run test:languages -- --update

すべての失敗したテストファイルの期待されるトークンストリームを更新 (上書き) します。このコマンドを実行すると、言語テストがすべて合格します。

注意: このコマンドを使用すると、テストファイルの作成/更新は簡単になります。しかし、テストは正確であるとは限りません。挿入/更新されたトークンストリームは必ず注意深く確認してください!

簡略化されたトークンストリームの説明

Prism は、ハイライトするときにソースコードをトークンストリームに変換します。これは基本的にネストされたトークン (または配列、または文字列) のツリーです。

これらのツリーを手動で記述するのは難しいため、テストランナーはこれの簡略化されたバージョンを使用します。

次のルールを使用します。

トークンオブジェクトは配列に変換されます: [token.type, token.content] (ただし token.content はネストされた構造体である可能性があります)。
空か空白のみを含むすべての文字列は、トークンストリームから削除されます。
すべての空の構造体は削除されます。

簡略化されたトークンストリームにはトークンのエイリアスは含まれません。

詳細については、テストランナーのテスト (tests/testrunner-tests.js) を読むと、変換を理解できます。

テストスイートの実行