Postmanでマルチパート（Multipart/form-data）を制する：ファイルアップロードAPIの「完璧なテスト」戦略
エンジニア諸君、APIテストで「ファイルがアップロードできない」「400 Bad Requestが消えない」といった泥沼にハマったことはないか？
特に `multipart/form-data` は、Postman上で単にフォームデータをポチポチ追加するだけでは不十分だ。本稿では、ファイルアップロードAPIを完璧にテストし、チームの開発生産性を爆速化させるための「現場の極意」を伝授する。
—
1. 完璧なマルチパート・リクエストの組み立て方
Postmanでファイルを送信する際、最も多いミスが「Content-Type」の二重設定だ。
陥りがちな罠：Content-Typeの衝突
ヘッダータブで `Content-Type: multipart/form-data` を手動で設定してはいけない。これを行うと、境界線（boundary）の定義が欠落し、サーバー側でパースエラーが発生する。
【正攻法】
1. Bodyタブ で `form-data` を選択。
2. Keyの右側にあるドロップダウン（`Text` と表示されている箇所）を `File` に変更。
3. 値をアップロードしたいファイルに設定。
4. Headersタブを空にする。 Postmanが自動で `boundary` パラメータを含んだ正しい `Content-Type` を生成してくれる。これこそが「無駄なバグを生まない」鉄則だ。
—
2. 大容量・複数ファイル送信時の「隠れた武器」
巨大なバイナリデータや、複数の画像を一度に送る際、手動設定では限界がある。ここで現場のエンジニアが使うべきテクニックを紹介する。
実践：Pre-request Scriptを活用したデータ動的生成
ファイルパスをハードコーディングすると、チーム開発で破綻する。環境変数を使って動的に制御せよ。
// Pre-request Script: 実行前に環境変数を整理
// 巨大なバイナリをテストする際は、タイムアウト設定を延長しておくのが定石
pm.globals.set(“upload_timeout”, 30000);
console.log(“アップロードテスト開始: ” + pm.info.requestName);
大容量データの罠
Postmanで数GBのファイルを送る場合、メモリを食いつぶしアプリ自体がクラッシュすることがある。実務上のベストプラクティスは、テスト用に「数KB〜数MBのダミーファイル（画像・動画）」をリポジトリ内に用意し、それらを相対パスで指定することだ。
—
3. 開発スピードを底上げする「神」テクニック
必須のキーボードショートカット
- `Cmd/Ctrl + Enter`: リクエスト送信（基本だが必須）
- `Cmd/Ctrl + Shift + F`: 全リクエストの検索（大規模コレクションの救世主）
- `Cmd/Ctrl + B`: サイドバーの開閉（広大な画面でデバッグ効率化）
チーム開発を加速させる「環境設定（Environment）」の共有化
個人のローカル環境を環境変数に抽出し、JSONファイルとしてGit管理せよ。
{
“id”: “uuid-v4-xxxx”,
“name”: “Production-API-Config”,
“values”: [
{ “key”: “base_url”, “value”: “https://api.production.com”, “enabled”: true },
{ “key”: “auth_token”, “value”: “{{secret_token}}”, “enabled”: true }
]
}
これをエクスポートして共有すれば、チーム全員が同じ条件でテストを実行できる。
—
4. 現場のテックリードが推奨する「設定構成」のベストプラクティス
テストの自動化を見据えるなら、コレクションを以下の構成に分割せよ。
1. `01_Auth`: トークン取得専用リクエスト（全リクエストの前提）
2. `02_Upload_Success`: 正常系（画像、動画、PDFなど）
3. `03_Upload_Error`: 異常系（ファイルサイズ超過、空ファイル、非対応MIMEタイプ）
テストスクリプトのテンプレート（Testsタブ用）：
// レスポンス検証の標準化
pm.test(“Status code is 200”, function () {
pm.response.to.have.status(200);
});
pm.test(“Response time is less than 2000ms”, function () {
pm.expect(pm.response.responseTime).to.be.below(2000);
});
pm.test(“Upload successful flag”, function () {
const jsonData = pm.response.json();
pm.expect(jsonData.success).to.eql(true);
});
—
まとめ：ツールを「使う」のではなく「操る」
Postmanは単なるHTTPクライアントではない。正しく設定し、スクリプトで自動化し、チームで環境を共有すれば、それは最強の「API品質保証ツール」に化ける。
- ヘッダーの自動生成に任せること（手動設定は悪）
- ダミーファイルで運用を回すこと（巨大データは別枠で検証）
- 環境変数をGit管理すること（ナレッジを属人化させない）
この3点を守るだけで、君たちのチームのデバッグ時間は劇的に減るはずだ。さあ、今すぐコードベースのテストを洗練させ、より強固なAPI設計を目指してくれ。健闘を祈る。