つまり、このエラーが本当に速度の問題であることはまれです。たいていは、どこかのステップが決して起こらないことを待っています。私が確認する順に、原因と対処を並べるとこうなります。

1. ロケーターが何にも一致せず、click() や fill() がテストの持ち時間が尽きるまで待ち続けている。よくある理由は、テストIDの変更、テキストの変更、手前に被さったダイアログです。ロケーターを直します。
2. ページ遷移や waitForURL() が、いつまでも来ないページを待っている。リダイレクトやログイン画面、初回起動の画面のせいで、アプリが別の場所へ行ってしまったケースです。待つ対象を直します。
3. セットアップが本当に遅い。初回リクエストでようやくコンパイルを始める開発サーバー、ゼロスケールから起き上がるバックエンド、beforeEach のたびにUIで行うログインなどです。環境を直すか、セットアップを1回で済ませます。
4. テストが単純に長い。そのときに限って、test.slow() か test.setTimeout() でそのテストに時間を足します。

どれであっても、最初にやることは、時間切れの瞬間にまだ動いていたステップを見つけることです。次にやるのが actionTimeout の設定で、そうしておけば次の失敗ではエラーのほうがステップを教えてくれます。

30秒に含まれるもの

#

テストタイムアウトは、フィクスチャのセットアップ、beforeEach フック、テスト関数が共有する1つの持ち時間です。テストが終わると、afterEach フックとフィクスチャのティアダウンには、同じ長さの持ち時間が別に与えられます。beforeAll と afterAll も同じ値を受け取りますが、どのテストとも時間を共有せず、失敗したときも専用のメッセージを出します。

この持ち時間の中で、自分の時計を持っているのはアサーションだけです。await expect(locator).toBeVisible() はデフォルトで5秒たつと諦め、何を探していたのかを正確に教えてくれます。アクションとページ遷移はそうではありません。actionTimeout と navigationTimeout のデフォルトは無制限です。このエラーがこれほど曖昧な理由は、すべてここにあります。決して現れない要素へのクリックは失敗しません。ほかの何かがテストを終わらせるまで、行儀よく待ち続けるだけです。

実行を終わらせうるタイムアウトをすべて、それぞれが出すメッセージと一緒に並べました。メッセージは、私のプロジェクトに入っている中で最も古い1.58と最も新しい1.63からそのまま写しています。

アクション、ページ遷移、実行全体の行にはデフォルト値がないので、表の数字は自分で設定した値が入る場所です。

5つのテストと、名前の変わったテストID

#

2月、私が作っている見積もりアプリのテストスイートで、5つのテストが1回の実行の中でまったく同じように失敗しました。このスイートは、開発サーバーが配信するアプリのWeb版を、ワーカー1つで、シードデータを入れ直したローカルのバックエンドに対して動かしています。5つのうち最初の1つを、少し削って載せます。

  1) [default] › tests/templates.spec.ts:50:7 › Templates › should edit a template ───

    Test timeout of 30000ms exceeded.

    Error: locator.click: Target page, context or browser has been closed
    Call log:
      - waiting for locator('[data-testid="template-item"]').filter({ hasText: 'E2E Edit Template' }).locator('[data-testid="edit-template"]')


      57 |       .locator('[data-testid="template-item"]')
      58 |       .filter({ hasText: "E2E Edit Template" });
    > 59 |     await item.locator('[data-testid="edit-template"]').click();
         |                                                         ^
      60 |     await page.waitForTimeout(500);

Target page, context or browser has been closed の行だけ見ると、ブラウザが落ちたように読めます。違います。足元でページが閉じられたときに、アクションが出すメッセージです。30秒が尽きてPlaywrightがテストを片付け、まだ待っていたクリックが、失ったページのことを報告したわけです。組み込みの page フィクスチャを使っていれば、この行は Error: locator.click: Test timeout of 30000ms exceeded. のようにタイムアウトをもう一度伝えていたはずです。このテストは beforeAll で自前のブラウザコンテキストを開いているので、クリックには汎用のメッセージが届きました。

役に立つのはコールログです。クリックは [data-testid="template-item"] を待っていました。その10時間前、私は一覧の行コンポーネントのテストIDを template-item から template-item-${name} に変えていました。ネイティブアプリのE2Eテストが、名前で特定の行を選べるようにするためです。= を使った属性セレクターは値全体が一致しないとマッチしないので、Webのテストはページのどこにも存在しない要素を探していたことになります。アクションタイムアウトもないので、そのクリックはテストの持ち時間が尽きるまで待つしかありませんでした。30秒の失敗が5つで2分30秒。実行全体は3.8分でした。

私が最初に足したのはリトライでした。30分もしないうちに設定には retries: process.env.CI ? 2 : 1 が入り、そこに付けたコメントには今も “for flaky browser crashes”（ときどき起きるブラウザのクラッシュ対策）と書いてあります。次の実行では、同じ5つのうち4つがリトライも含めてまた失敗し、実行時間は3.8分から6.4分に延びました。これらのdescribeブロックはシリアルモードで動きます。1つが失敗するとグループの残りはスキップされ、リトライはグループを最初からやり直します。そのせいで、壊れたクリックはどれも30秒を2回ずつ待ちました。毎回同じ理由で失敗するテストは、リトライでは救えません。代償を2回払うだけです。

修正は前方一致でした。

const item = page
  .locator('[data-testid^="template-item-"]')
  .filter({ hasText: "E2E Edit Template" });
await item.locator('[data-testid="edit-template"]').click();

もっと広い教訓は、テストIDも一種の契約だということです。私には、このID 1つに頼るテストスイートが2つあり、どちらもお互いの存在を知りませんでした。Playwrightのベストプラクティスのガイドが、私が使ったようなCSSセレクターよりも getByRole() のようなユーザーから見える属性に基づくロケーターを勧めているのも、ユーザーが気づきもしないDOMの変更でテストが壊れないようにするためです。

止まったステップを見つける

#

まずコールログを読みます。これは時間切れの瞬間にまだ動いていたステップのもので、waiting for locator(...) の後に何も続いていなければ、ロケーターが最後まで何にも一致しなかったということです。

それで足りなければトレースを開きます。私のアプリのスイート2つ、見積もりアプリのものと、私が作っているマーケットプレイス兼コミュニティアプリのものは、どちらも trace: "on-first-retry" を使っています。最初のリトライのときだけ記録する設定なので、retries が1以上でないと記録されません。リトライを使わないなら "retain-on-failure"、1回だけ試すなら --trace on です。あとはトレースを直接開くか、HTMLレポートから開きます。

npx playwright show-trace test-results/<test-folder>/trace.zip
npx playwright show-report

終わらなかったアクションは、一覧の最後のほうでエラーが付いている項目です。それを選んでスナップショットを見てください。Playwrightが待っていた時点のページそのもので、期待していた要素を自分で探せます。私のケースなら、テストが探していないIDを付けた行が、ちゃんとそこにあったはずです。

最近のバージョンは、失敗時のスクリーンショットの隣に error-context.md も書き出します。失敗した瞬間のページをテキストのスナップショットにしたもので、要素が見つからないケースなら、これだけで十分なこともよくあります。

落とし穴が1つあります。--debug はInspectorを開くと同時に、--max-failures=1、--headed、--workers=1 と一緒に --timeout=0 も設定します。--debug で通ったテストは、30秒については何も教えてくれていません。

すべてのアクションに上限を

#

私の設定ファイルには、アクションタイムアウトを設定しているものが1つもありません。だから見つからない要素1つのために、30秒を5回も使ったわけです。use に2行足せば変わります。

import { defineConfig } from "@playwright/test";

export default defineConfig({
  timeout: 30_000,
  expect: { timeout: 5_000 },
  use: {
    actionTimeout: 10_000,
    navigationTimeout: 15_000,
    trace: "retain-on-failure",
  },
});

すると同じ壊れたロケーターが、テストにまだ時間が残っているうちに、こう失敗します。

    TimeoutError: locator.click: Timeout 10000ms exceeded.
    Call log:
      - waiting for locator('[data-testid="template-item"]').filter({ hasText: 'E2E Edit Template' }).locator('[data-testid="edit-template"]')

どのステップで、どのアクションが、どれだけ待ったのかが全部わかります。2つの値はテストタイムアウトより十分小さくしておくのがいいと思います。そうすれば、止まったステップ1つが持ち時間を使い切り、曖昧なメッセージの陰に隠れることはありません。2月の問題は30秒ではありませんでした。あのクリックにかかっていた時計がそれ1つだけだったので、それが鳴ったというだけです。

タイムアウトを延ばすのは長いテストだけ、止まったテストではなく

#

タイムアウトを延ばすのが正解なのは、テストが実際に時間のかかる仕事をしているときです。あるステップが起こらないことを待っているときには不正解です。数字を大きくしても、失敗が遅れて届くだけですから。どちらなのかは、たいていトレースを見ればはっきりします。アクションが1つずつ終わっていて単に数が多いなら長いテスト、1つのアクションが最後まで waiting for のまま止まっているなら止まったテストです。

長いテストなら、スイート全体ではなく、長さがある場所に時間を足します。マーケットプレイスアプリのスイートには、スクリーンショットを撮りながらチャット画面を一通り回るスモークテストが1つあり、このテストには3分を与えています。

test("chat: open, send a message, go back", async ({ page }) => {
  test.setTimeout(180_000);
  // ...
});

describe の中で test.setTimeout() を呼ぶと、グループ内のすべてのテストに効きます。見積もりアプリのスイートの作業コスト（job-cost）のテストが1分をもらっているのは、この方法です。test.slow() は今のタイムアウトが何であれ3倍にし、条件を渡すこともできます。beforeEach の中で testInfo.setTimeout() を使えば、そのフックを通るすべてのテストが延びます。

test("slow in WebKit", async ({ page, browserName }) => {
  test.slow(browserName === "webkit", "This page is slow in WebKit");
  // ...
});

test.beforeEach(async ({ page }, testInfo) => {
  testInfo.setTimeout(testInfo.timeout + 30_000);
});

持ち時間を毎回静かに削っていくものが、もう1つあります。固定のスリープです。見積もりアプリのスイートには、ほぼすべてのspecファイルにまたがって、page.waitForTimeout() の呼び出しが100個以上あります。上の編集テストはクリックにたどり着く前に3秒眠っていますが、どれだけ眠っても助からなかったでしょう。PlaywrightのAPIドキュメントも、ここははっきりしています。“Never wait for timeout in production. Tests that wait for time are inherently flaky."（本番では決して時間で待たないこと。時間を待つテストは本質的に不安定です。）Webファーストアサーションは、もともと必要なだけ待ち、それ以上は待ちません。

// before
await page.locator('[data-testid="save-template"]').click();
await page.waitForTimeout(1500);
await expect(page.getByText("E2E Edited Template")).toBeVisible();

// after
await page.locator('[data-testid="save-template"]').click();
await expect(page.getByText("E2E Edited Template")).toBeVisible();

アサーションのタイムアウトにも同じ注意が要ります。2つのアプリのスイートはどちらも expect.timeout を15秒に上げていて、どちらも本番ビルドではなくアプリの開発サーバーを相手に動いています。余裕はできますが、遅いアサーションが2つ続けば、その2つで30秒を使い切ることもあります。そうなるとテストタイムアウトが先に切れて、また曖昧なメッセージに逆戻りです。

テストの時計ではないとき

#

メッセージに config.webServer が出てくるなら、まだテストは1つも動いていません。Playwrightは webServer のコマンドを起動し、その url が応答するまで待ってからテストを始めます。この待ち時間には別のタイムアウトがあり、デフォルトは60秒です。2つのアプリのスイートは、どちらも開発サーバーに2分を与えています。

webServer: {
  command: "npm run web -- --port 8081",
  url: "http://localhost:8081",
  reuseExistingServer: false,
  timeout: 120_000,
},

テストがローカルのサーバーではなくデプロイ済みの環境に向いているなら、最初のリクエストにどれだけかかるかを確かめてください。使っているホスティング先でようやく測ってみたら、ゼロスケールから起動するマシンが何かを返すまでに25〜33秒かかっていました。最初のクリックの前に、テストの持ち時間のほとんど、あるいは全部です。その話は「ゼロスケールと、再起動のたびに起きる30秒の障害」に書きました。

「No tests found」と出たら

#

No tests found は似て見えますが、タイムアウトではありません。Playwrightが探したものの、実行するものが何もなかったという意味です。デフォルトでは testDir の下で **/*.@(spec|test).?(c|m)[jt]s?(x) に一致するファイルを集め、testDir のデフォルトは設定ファイルがあるフォルダーです。私の設定は設定ファイルの隣の testDir: "./tests" を指しているので、ほかの場所に保存したspecは見えません。コマンドラインの引数はファイルパスに対してマッチさせる正規表現で、だからエラーには “Make sure that arguments are regular expressions matching test files.” という一文が付きます。何も実行せずに、Playwrightが何を集めたかだけを見るにはこうします。

npx playwright test --list

その一覧にspecがないなら、そもそもタイムアウトになりようがありません。Playwrightをこれから導入するところなら、スクリーンショット比較から始めようという私の考えは「小規模チームこそビジュアルテストを」に書いています。

デバッグには本当に時間を取られます。誰でもそうだと思います。最近は自分のアプリのバグ追いでXcodeとシミュレータにこもる日が多く、そのたびに思うのは、Xcodeにはほとんど誰も触らない強力なデバッグ機能が山ほどある、ということです。この記事では、長年かけて落ち着いた自分のデバッグ手順のうち、実際に時間の節約になっている部分をまとめます。

ブレークポイントは思っているより強力

#

ほとんどの人は、ガターをクリックしてブレークポイントを置いて終わりです。でも右クリックしてみると、デバッグのやり方が変わるくらいのオプションが出てきます。

条件付きブレークポイント

#

1000件を処理するループで、347番目だけがおかしいとします。346回もブレークポイントで止まるのは時間の無駄です。

for i in 0..<users.count {
    processUser(users[i])  // ここにブレークポイントを設定、条件: i == 347
}

ブレークポイントを右クリックして条件に i == 347 を入れれば、Xcodeは条件が真のときだけ止まります。userId == "abc123" や error != nil のような条件でも同じです。

シンボリックブレークポイント

#

メソッドがどこから呼ばれているのか分からないときに使います。ブレークポイントナビゲータ（Cmd+8）で「+」ボタンをクリックし、「Symbolic Breakpoint」を選びます。

どのビューコントローラがいつロードされるか全部見たければ、シンボルを viewDidLoad にします。Xcodeがすべての呼び出しで止まります。うるさすぎるなら MyViewController.viewDidLoad のように絞り込みましょう。

私が常設しているのはこの3つです。

• UIViewAlertForUnsatisfiableConstraints：Auto Layoutの競合をその場で捕まえる
• objc_exception_throw：クラッシュする前にObjective-Cの例外で止まる
• malloc_error_break：メモリ割り当ての問題を見つける

例外ブレークポイント

#

新しいプロジェクトで最初にやるべき設定だと思います。ブレークポイントナビゲータで「+」→「Exception Breakpoint」を追加しておくと、アプリが落ちた後ではなく、何かがスローされた瞬間にXcodeが止まってくれます。

コンソールに謎のクラッシュとしてしか出てこないnilアンラップの問題を、これで何度も捕まえてきました。

ブレークポイントアクション

#

ブレークポイントは実行を止めなくてもいいんです。ブレークポイントを編集して「Add Action」をクリックすると、こんなことができます。

• 止めずに変数を出力する："User count: @(users.count)@"
• LLDBコマンドを自動実行する
• シェルスクリプトを実行する
• 音を鳴らす（めったに通らないコードパスの確認に使っています）

「Automatically continue after evaluating actions」にチェックを入れれば、ブレークポイントはフローを止めないロガーになります。

LLDB：実際に使うコンソールコマンド

#

ブレークポイントで止まったとき、下のコンソールはクラッシュログを眺めるだけの場所ではありません。あれはLLDBで、本当に便利です。

基本

#

(lldb) po user
▿ User
  - id: "123"
  - name: "John Doe"
  - email: "john@example.com"

po はオブジェクトを読みやすい形で出力します。私のLLDB利用の9割はこれです。

もう少し詳しく見たいときは p を使います。

(lldb) p user.name
(String) $R0 = "John Doe"

ローカル変数を一度に全部見るなら、こうです。

(lldb) frame variable

実行中に値を変える

#

LLDBの本領はここです。再コンパイルせずに変数を書き換えられます。

(lldb) expr user.name = "Jane Doe"
(lldb) expr index = 0

バグを見つけて、リビルドせずに修正を試したい。そんなときは変数を変えてそのまま続行すればいいわけです。エッジケースを絞り込むとき、いつもこれで値を差し替えています。

メソッドの呼び出しもできます。

(lldb) po self.refreshUI()
(lldb) expr navigationController?.popViewController(animated: true)

ナビゲーション

#

(lldb) bt              # コールスタックを表示
(lldb) frame select 3  # 別のスタックフレームにジャンプ
(lldb) continue        # 実行を続ける（または単に 'c'）
(lldb) n               # ステップオーバー（次の行）
(lldb) s               # 関数にステップイン

ウォッチポイント

#

変数がいつ変わるのか知りたければウォッチポイントです。

(lldb) watchpoint set variable user.isLoggedIn

コードのどこから変更されても、その瞬間に実行が止まります。想定外の状態変更を追うときには手放せません。

Console.app：隠れたデバッグツール

#

Xcodeのコンソールで十分な場面は多いですが、システムログもクラッシュレポートも全部見たい、となったらConsole.appの出番です。

OSLogを使っていれば（使うべきです）、Console.appでログを検索したりフィルタしたりできます。

import os.log

let logger = Logger(subsystem: "com.example.app", category: "networking")

logger.info("Starting API request")
logger.debug("Request URL: \(url.absoluteString)")
logger.error("Failed to decode: \(error.localizedDescription)")

Console.app側の手順はこうです。

1. シミュレータか接続中のデバイスを選ぶ
2. サブシステムで絞る：subsystem:com.example.app
3. レベルで絞る：subsystem:com.example.app AND level:error

よく使うフィルタ述語は保存できます。私はネットワークリクエスト用、データベース操作用、エラーと警告だけを出す用の3つを持っています。

print()ではなくOSLogを使う理由

#

OSLogは、print() をあちこちに撒くよりずっとましです。構造化されているのでレベルやカテゴリで絞り込めますし、ログ自体が最適化されていてアプリを遅くしません。本番では機密データを自動でマスクしてくれて、アプリが落ちた後もログは残ります。

とっさの確認には print() で構いません。後で見返す可能性があるものはOSLogに残しましょう。

Console.appの高度なフィルタリング

#

Console.appはかなり凝った述語クエリに対応しています。私がよく使うのはこのあたりです。

# アプリ内のすべてのエラーと障害
subsystem:com.example.app AND (level:error OR level:fault)

# 失敗したネットワークリクエスト
subsystem:com.example.app AND category:networking AND eventMessage CONTAINS "failed"

# 過去5分間のすべて
subsystem:com.example.app AND timestamp >= now(-5m)

ログはエクスポートしてバグレポートに添付することもできます。Xcodeのコンソールからコピペするよりずっと楽です。

ビューデバッグ

#

UIが壊れているのに原因が分からないとき、いちばん早いのはビューデバッガです。

アプリを実行して壊れた画面まで進み、Xcodeのデバッグバーで「Debug View Hierarchy」をクリックします（またはCmd+Shift+D）。ビュー階層全体が3Dで分解表示されます。

回してみると、いろいろ見えてきます。

• 他のビューの裏でレンダリングされているビュー
• 画面のはるか外にいるビュー
• サイズがゼロのビュー
• 選択したビューの制約チェーン全体

私はこれで、タップイベントを吸い込んでいた透明なボタンや、0x0でレンダリングされていたラベル、いつの間にか幅10,000ピクセルになっていた画像を見つけたことがあります。

Auto Layoutのデバッグ

#

ビュー階層に紫の警告アイコンが出ていたら制約の競合です。クリックすると、どの制約同士がぶつかっているのかXcodeが正確に教えてくれます。

制約には識別子を付けておきましょう。

heightConstraint.identifier = "ProfileImageHeight"

制約が壊れたとき、エラーにメモリアドレスではなく "ProfileImageHeight" が出るようになります。ログの読みやすさが段違いです。

LLDBから制約ツリーを出力することもできます。

(lldb) po view.hasAmbiguousLayout
(lldb) po view._autolayoutTrace()

時間を節約してくれるシミュレータ機能

#

スローアニメーション

#

Debug → Slow Animations で、すべてが1/10の速度になります。トランジション中に何が起きているのか、アニメーションがなぜ変に見えるのかを確かめるのにちょうどいいです。

メモリ警告のシミュレート

#

Debug → Simulate Memory Warning。メモリ不足のときのアプリの挙動をテストできます。これで画像キャッシュのバグをいくつも見つけました。メモリ警告が来るまでは普通に動いているのに、来た途端に画像が全部消えるやつです。

Network Link Conditioner

#

Xcode → Open Developer Tools → Network Link Conditioner

3GやLTE、高パケットロス、完全オフラインをシミュレートできます。WiFiでは平気なAPIリクエストがモバイル回線でタイムアウトする、という経験があるなら、原因はこれで再現できます。

私は遅延500ms・パケットロス10%の「Bad Network」プロファイルを常備しています。速いオフィスWiFiでは絶対に出ない、タイムアウトのバグやローディング表示の問題が引っかかります。

ステータスバーのオーバーライド

#

シミュレータのステータスバーを右クリックすると、時刻、バッテリー残量、電波強度、キャリアを上書きできます。スクリーンショットを揃えたいときや、バッテリー残量ごとのUI確認に便利です。

位置情報のシミュレーション

#

Debug → Location で、机から動かずにいろいろな場所を再現できます。任意の座標、街歩き、高速道路の走行まで一通り揃っています。位置情報を使う機能のテストや、特定の地域でしか起きない不具合の調査で重宝します。

メモリデバッグ

#

Debug Memory Graph

#

Debug Memory Graphボタン（Cmd+Shift+M）を押すと、メモリ上のすべてのオブジェクトとその参照関係、そして肝心の「どれがリークしているか」をXcodeが見せてくれます。

紫のビックリマークがリークです。クリックすると保持サイクルが見えます。

いちばんよく見かけるリークはこれです。

class ViewController: UIViewController {
    var onComplete: (() -> Void)?

    func setupHandler() {
        onComplete = {
            self.dismiss(animated: true)  // ❌ selfを強く参照
        }
    }
}

weak selfで直します。

onComplete = { [weak self] in
    self?.dismiss(animated: true)  // ✓ 保持サイクルなし
}

デリゲートもweakにしておきます。

weak var delegate: ManagerDelegate?  // 単なる 'var' ではなく

Instruments

#

本腰を入れてメモリを調べるならInstrumentsです（Product → Profile、またはCmd+I）。

Allocationsを使うと、オブジェクトの割り当てすべて、時間経過に伴うメモリの増え方、どのクラスがメモリを食っているか、割り当てが起きた場所のスタックトレースまで見えます。

私が探すのはだいたい、時間に比例して増え続けるメモリ（ほぼリークです）、想定外に大きい割り当て（画像1000枚をうっかり一気に読んでいないか？）、解放されているはずなのに残っているオブジェクト、この3つです。

操作の前後で世代をマークして（小さな旗のボタン）、残ってはいけないものが残っていないか確認しましょう。

パフォーマンスプロファイリング

#

Time Profiler

#

Product → Profile → Time Profiler。アプリで重い操作をしながら記録して、コールツリーを読みます。

「Self Weight」でソートするとボトルネックが見つかります。ある関数のself weightが40%なら、時間はそこに消えています。

以前、JSONのパース関数が毎秒1000回呼ばれているのを見つけたことがあります。バックグラウンドキューに移したら、UIのカクつきが止まりました。

Main Thread Checker

#

バックグラウンドスレッドでのUI更新は、Xcodeが自動で捕まえてくれます。こんな表示が出たら、

Main Thread Checker: UI API called on a background thread: -[UILabel setText:]

こういうことをやってしまっています。

URLSession.shared.dataTask(with: url) { data, response, error in
    self.label.text = "Loaded"  // ❌ クラッシュ！
}

直すとこうなります。

URLSession.shared.dataTask(with: url) { data, response, error in
    DispatchQueue.main.async {
        self.label.text = "Loaded"  // ✓
    }
}

ランタイム診断

#

Edit Scheme → Run → Diagnostics。ここに並んでいるチェックボックスは、手作業では絶対に見つからないバグを捕まえてくれます。

Address Sanitizer

#

メモリ破壊を見つけます。use-after-free、バッファオーバーフロー、メモリリーク。アプリは2〜3倍遅くなりますが、他の方法ではほぼ追跡不可能なバグを捕まえてくれます。たまにしか起きないクラッシュを追うときにオンにします。

Thread Sanitizer

#

データ競合とスレッド絡みの問題を捕まえます。有効にしてアプリを普通に触っているだけで、競合状態があればThread Sanitizerが見つけてくれます。

Address SanitizerとThread Sanitizerは同時に使えないので、妙なクラッシュを追うときは交互に切り替えています。

Zombie Objects

#

解放済みオブジェクトへのメッセージを捕まえます。有効にしておくと、解放されたメモリに触った瞬間をXcodeが正確に教えてくれます。

*** -[MyViewController viewDidLoad]: message sent to deallocated instance 0x600001234000

つけっぱなしは禁物です。オブジェクトが解放されなくなるので、メモリは増える一方になります。ただ、特定のuse-after-freeバグを突き止めるには最高です。

よくあるデバッグシナリオ

#

起動時にクラッシュする

#

まず例外ブレークポイントを追加します。たいていはこれで捕まります。

だめなら、Info.plistのキー漏れ、初期化コードでの強制アンラップ、依存性注入の失敗あたりを疑います。

UIが更新されない

#

毎回、原因はこのどれかです。

1. 更新がメインスレッドで行われていない
2. アウトレットがつながっていない
3. ビューがそもそも表示されていない（LLDBで po view.window を確認。nilなら階層に入っていません）

テーブルビューやコレクションビューなら、reloadData() の呼び忘れです。

メモリ警告でアプリが落ちる

#

Instruments Allocationsで何がメモリを掴んでいるか確認します。たいていは、キャッシュから解放されない画像、解放されないビューコントローラ（保持サイクル）、際限なく育つ配列や辞書のどれかです。

シミュレータでメモリ警告をシミュレートして、クリーンアップ処理をテストしておきましょう。

原因不明のクラッシュ

#

サニタイザーを全部オンにします。間欠的ならたぶんスレッドの問題なのでThread Sanitizerで、システムフレームワーク内で落ちているならたぶんメモリ破壊なのでAddress Sanitizerで走らせます。

再現できないクラッシュ

#

クラッシュが他人のスマホで起きた場合でも、レポートはたいていどこかに残っています。TestFlightやApp Storeのビルドなら、XcodeのOrganizer（Window → Organizer → Crashes）に、解析データの共有をオンにしているユーザーのクラッシュレポートが集まってきます。ビルドと一緒にdSYMもアップロードしてあれば、シンボル化された状態で見られます。テスターの端末なら、レポートは端末そのものの「設定 → プライバシーとセキュリティ → 解析および改善 → 解析データ」に、アプリ名で始まる .ips ファイルとして残っているので、AirDropで送ってもらいましょう。まずはクラッシュしたスレッドのスタックトレースを読み、そこから上のシナリオを順に当たっていきます。

シミュレータでOTA更新をデバッグする

#

私のアプリはOTA（Over-the-Air）アップデートを配信しているのですが、このフロー全体のデバッグにはシミュレータがいちばん手軽です。

まずネットワークトラフィックを見ます。アプリのサブシステムで絞ったConsole.appに、マニフェストのリクエストとレスポンスがリアルタイムで流れてくるので、どのヘッダーを送っていてサーバーが何を返しているかが正確に分かります。

次に、わざとネットワークを悪くします。Network Link Conditionerで、遅い回線やパケットロスのときに更新フローがどう振る舞うかを確かめます。アプリは固まらないか。ローディング表示は出るか。ちゃんとフォールバックするか。

更新チェックの周辺にはログを仕込みます。チェック開始時、更新があったとき、ダウンロード開始時、新しいバンドルのロード時、それぞれで記録しています。

import os.log

let logger = Logger(subsystem: "com.example.app", category: "updates")

logger.info("Checking for updates...")
let update = try await Updates.checkForUpdateAsync()
logger.info("Update available: \(update.isAvailable)")

最後に、マニフェストのエンドポイント単体もテストしておくと安心です。アプリが送るのと同じヘッダーでcurlできます。

curl -H "expo-protocol-version: 1" \
     -H "expo-platform: ios" \
     -H "expo-runtime-version: 1.0.0" \
     https://updates.example.com/manifest

クライアント側を掘り始める前に、サーバーが正しいデータを返しているかをここで確認できます。

サードパーティツール

#

Charles Proxy / Proxyman

#

ネットワークトラフィックの全表示、リクエストとレスポンスの改変、エラー条件のテスト。APIデバッグには欠かせません。

ProxymanはCharlesよりUIがよく、macOSに馴染む感じがします。去年乗り換えて、戻る気はありません。

Reveal

#

Xcodeのビューデバッガに似ていますが、もっと強力です。Xcodeにつながずに実機で動くので、テスターの端末でレイアウト問題を追うのに向いています。

シミュレータと実機の違い

#

デバッグの大半はシミュレータでやっています。ケーブルも署名もいらず、インストールを待つ必要もないので速いからです。とはいえ、シミュレータの正体はMacのプロセッサの上で動くiOSのビルドで、メモリもネットワーク接続もMacのものをそのまま使っています。スマホの上でしか起きないバグは、そこでは出てきません。

なので、ロジックの組み立てとデバッグはシミュレータで済ませ、リリース前にはサポート対象の中でいちばん古いiPhoneでアプリを動かしています。パフォーマンス、メモリの逼迫、ハードウェアに触れる部分は、実機で動かすまでは本当の意味でテストしたことになりません。

実機で動かす

#

iPhoneをつないで実行先に選び、Signing & Capabilities でチームを設定します（自分のスマホで動かすだけなら無料のApple IDで足ります）。iOS 16以降は、スマホ側でも「設定 → プライバシーとセキュリティ」でデベロッパモードをオンにする必要があり、初回は再起動がかかります。オンにすると、スマホ自体の「設定 → デベロッパ」メニューにNetwork Link Conditionerが現れ、Macと同じ悪条件のネットワークプロファイルが使えるようになります。

ワイヤレスデバッグ

#

一度だけUSBでつなぎ、Window → Devices and Simulators で「Connect via network」にチェックを入れて、ケーブルを抜きます。同じWiFiにいる限り、デバイスはXcodeから見え続けます。

Device Console

#

Window → Devices and Simulators → Open Console。システムログ、アプリログ、クラッシュレポートと、何でも見えます。Xcode側のコンソールよりずっと詳細です。

テスターから「アプリが落ちた」と言われたら、必ずデバイスをつないでコンソールログを取らせてもらいます。すべてを説明してくれるシステムレベルのエラーが残っていることが多いんです。

実際のデバッグ手順

#

1. 例外ブレークポイントがなければ追加する
2. バグを再現する
3. 怪しい場所の近くにブレークポイントを置く
4. LLDBの po で値を確認する
5. 変数を書き換えて、再コンパイルせずに修正を試す
6. UI絡みならビュー階層を見る
7. パフォーマンス絡みならInstrumentsでプロファイルする
8. メモリかスレッド絡みならサニタイザーをオンにする

コツは症状から逆算することです。クラッシュ？例外ブレークポイント。遅い？Time Profiler。メモリ？Instruments。UIが変？ビューデバッガ。

もっと早く知りたかったこと

#

アサーションを使いましょう。ロジックの誤りがバグになる前に捕まります。

assert(users.count > 0, "Users array should never be empty here")

デバッグを始める前にコミットしておくこと。仮説を試すためにあちこち書き換え始めると、必ず戻したくなります。

終わったらprint文は消すこと。少なくとも #if DEBUG で囲んでおきましょう。古いデバッグログは、次のバグを見えにくくします。

LLDBはちゃんと覚えること。アプリを20回リビルドするより速いです。

そして、シミュレータは本物の電話ではありません。実機でしか出ないバグは、ほぼ例外なくスレッドかメモリの問題です。あるいはパフォーマンスの問題。シミュレータはiPhoneのチップではなくMacのCPUで動いていますから。

常に開いているツール

#

• Xcode（当然）
• アプリのサブシステムで絞ったConsole.app
• ネットワークデバッグ用のProxyman
• 事態が深刻になってきたらInstruments

どのツールも万能ではありません。ビューデバッガはメモリリークを見つけてくれませんし、InstrumentsはAuto Layoutの競合を解いてくれません。結局のところ、腕の見せどころは症状に合ったツールを選ぶことで、それは回数をこなすうちに身につきます。保持サイクルを何度も踏めば、スタックトレースを見た瞬間に匂いで分かるようになります。デバッグが楽しくなることはたぶんないですが、少なくとも苦行ではなくなります。