Testing Files Generator
日本語

テスト用の破損ファイルを作る方法

健全なファイルしか見せたことのない検証は、本当にはテストされていません。ここでは、意図的に壊してあり、求めたとおりのサイズで出てきて、システムがそれをどう扱うべきかを示すマニフェストを伴うファイルの作り方を説明します。

短い答え

tfg generate --format png --size 2mb --damage zero-head --out ./outは、ちょうど2097152バイトで先頭のバイトがゼロのPNGを書き出し、隣のマニフェストにはシステムがそれを拒否すべきだと記録されます。

よくあるやり方

手作業で壊したファイルがよくないテストになる理由

よくあるのは、16進エディタ、いくつかのランダムなバイトを反転させるスクリプト、headやtruncateでファイルを短く切る方法です。一度は使えますが、あとで手間がかかります。

得られるもの

破損したファイルも、求めたサイズのままです

ファイルは通常どおり生成され、ディスクへ向かう途中で壊されます。求めたサイズは保たれ、同じコマンドは同じバイトをもう一度書き出します。

tfg generate --format png --size 2mb --damage zero-head --out ./out
tfg generate --format pdf --size 1mb --count 5 --damage zero-head:bytes=16 --out ./broken
tfg generate --format zip --size 5mb --damage truncate:missing=30 --out ./cut
tfg generate --format jpg --size 500kb --damage append-junk --out ./tail

設定はコロンの後ろに書きます。オプションは繰り返せて、破損は書いた順に適用されます。32種類すべての形式で使えます。

できること

どんな破損がありますか。

これはプログラムが出力する一覧で、このページを作るときにプログラムから読み取っています。tfg damageは同じ一覧を出力し、tfg damage <id>はそのうちの1つが受け取る設定を示します。

破損 バイトへの作用 最小ファイル 設定
append-junk ファイルの末尾の後ろにランダムなバイトを書き込み、指定したサイズをそのまま保ちます。末尾に何かが付いたまま届いたファイルと同じ形です。 64 bytes
truncate ファイルの末尾を切り落とし、指定したサイズをそのまま保ちます。途中で止まったアップロードやコピーが残すのと同じ形です。 4 missing
zero-head ファイルの先頭のバイトをゼロで上書きし、長さは変えません。ほとんどのリーダーはまずそこを見るので、この破損にはほぼどれも気づきます。 8 bytes

zero-headはファイルの先頭をゼロで上書きします。ほとんどのリーダーはまずそこを見ます。ファイルが何であるかを示すシグネチャとヘッダーです。そのため、ほぼどのリーダーでも気づきます。プレーンテキストやログにはシグネチャがありませんが、これらも拒否されます。ゼロのバイトの連なりはテキストではないからです。4バイト未満では、どのリーダーも文句を言わない破損になる形式があります。設定が4から始まるのはそのためです。

truncateはファイルの末尾を切り落とします。途中で止まったアップロードやコピーが残すのと同じ形ですが、ファイルは指定したサイズのままです。大きめに生成され、その先頭だけがディスクに届くからです。missingはファイル全体のうちどれだけが失われるかを示し、指定しなければ半分です。

append-junkはファイルの末尾の後ろにランダムなバイトを書き込みます。指定しなければ64バイトで、末尾に何かが付いたまま届いたファイルと同じ形です。同じコマンドは同じバイトを付け加えます。

マニフェストの内容

何が起こるべきかを示すマニフェスト

破損が形式の規則に反する場合、項目はシステムがそれを拒否すべきことを示し、破損の内容がその横に記録されます。

"expected": {
  "outcome": "reject",
  "reason": "content_malformed",
  "confidence": "certain"
},
"damage": [
  {
    "type": "zero-head",
    "settings": {
      "bytes": "8"
    }
  }
]

リーダーによって扱いが分かれる場合、項目は推測せずにそう伝えます。末尾を切られたテキストファイルもテキストのままですし、ほとんどの画像ビューアーはPNGの終わりの後ろのバイトを読み飛ばします。そのため項目は答えをシステムに委ね、両方の答えを示し、理由を書きます。

"expected": {
  "outcome": "unspecified",
  "reason": "content_malformed",
  "detail": "A PNG ends at its IEND chunk and most viewers skip what follows it.",
  "confidence": "policy_dependent",
  "policy_options": ["accept", "reject"]
}

tfg damage <id>は、破損が答えをシステムに委ねる形式とその理由を一覧にします。

4種類のリクエストは、何かが書き込まれる前に拒否されます。どれもマニフェストの記述が誤ったファイルをディスクに残してしまうからです。

レシピで

1回の実行に健全なファイルと壊れたファイルを

両方を1つのレシピに入れると、マニフェストが各ファイルの期待を持つので、テストにどれがどれかの一覧は要りません。

version: 1
targets:
  - id: healthy
    format: pdf
    size: 1mb
    expected: accept
  - id: broken
    format: pdf
    size: 1mb
    damage:
      - zero-head

テストで

テストにする

テストはマニフェストを読み、起きたことが宣言どおりかどうかを確かめます。ファイル名の一覧は要りません。

import json, os

directory = "healthy-and-broken"
manifest = json.load(open(os.path.join(directory, "manifest.json")))

for entry in manifest["files"]:
    outcome = entry["expected"]["outcome"]
    if outcome == "unspecified":
        continue
    response = upload(os.path.join(directory, entry["path"]))
    if outcome == "reject":
        assert not response.ok
    else:
        assert response.ok

結果がunspecifiedのファイルはここでは除外します。システムがそれをどう扱うべきかは、あなた自身の方針で決まるからです。項目にはその理由が書かれ、policy_optionsには取りうる答えが並びます。

よい拒否は、きれいな拒否です。何が悪かったかを伝えるメッセージが、求めている答えです。サーバーエラー、ハング、書きかけで保存されたファイルは、このテストが見つけるために存在する欠陥です。

次へ

ここからどこへ