debugging-streamlit

Streamlit アプリのデバッグ

クイックスタート

make debug my_app.py

これにより、バックエンド（Streamlit/Python）とフロントエンド（Vite/React）の両方がホットリロード付きで起動します。アプリの URL は起動時に出力されます（デフォルトは http://localhost:3001、3000 は手動の make frontend-dev 用に予約されています。他のデバッグセッションが実行中の場合は 3002+ が使用されることがあります）。特定の厳格な要件がない限り、VITE_PORT を固定することは避けてください（最終手段です）。

ホットリロードの動作:

• フロントエンド: frontend/ のコードへの変更は数秒以内に反映されます。
• バックエンド: アプリスクリプトへの変更のみが再実行をトリガーします。Streamlit ライブラリ自体（lib/streamlit/）への変更は make debug の再起動が必要です。

ログファイル

各 make debug の実行は、work-tmp/debug/ 配下のセッションごとのディレクトリにログを書き込み、work-tmp/debug/latest/ を最新のセッションを指すように更新します。 latest/* はシンボリックリンクであるため、複数のデバッグセッションが同時に起動・停止していると移動する可能性があります。安定したログ参照が必要な場合は、make debug が出力するセッションディレクトリのパスを使用することをおすすめします。 正確なセッションディレクトリは、make debug の起動出力の Log files セクションで確認できます。

ファイル	内容
work-tmp/debug/latest/backend.log	Python の print() ステートメント、Streamlit のログ、エラー
work-tmp/debug/latest/frontend.log	ブラウザの console.log()、React のエラー、Vite の出力

ログは各セッションの開始時にクリアされ、終了後も事後分析のために保持されます。

ログサイズの警告: 長時間のデバッグセッションでは、ログが大きくなる可能性があります。ログファイル全体を読む代わりに、rg を使用して特定のパターンを検索してください:

# Search for specific debug messages
rg "DEBUG:" work-tmp/debug/latest/backend.log

# Search for errors (case-insensitive)
rg -i "error|exception|traceback" work-tmp/debug/latest/backend.log

# Search with context (3 lines before/after)
rg -C 3 "my_function" work-tmp/debug/latest/backend.log

# Search frontend logs for specific component
rg "MyComponent" work-tmp/debug/latest/frontend.log

すべてのデバッグ成果物（スクリプト、スクリーンショットなど）はこのディレクトリを使用して、整理された状態を保ってください。

デバッグ出力の追加

バックエンド（Python）:

print(f"DEBUG: session_state = {st.session_state}")

フロントエンド（TypeScript/React）:

console.log("DEBUG: props =", props)

フロントエンドの console.log() 出力は work-tmp/debug/latest/frontend.log（または現在のセッションの frontend.log ファイル）に表示されます。

ワークフロー

1. work-tmp/debug/ にテストスクリプトを作成または使用します（例: work-tmp/debug/test_feature.py）
2. make debug work-tmp/debug/test_feature.py を実行します
3. 起動の確認: work-tmp/debug/latest/backend.log で Error/Exception を、work-tmp/debug/latest/frontend.log でコンソールエラーを確認し、両方のサーバーが正しく起動したことを確かめます
4. 出力されたアプリ URL にブラウザでアクセスします（デフォルトは http://localhost:3001 ですが、3002+ の場合もあります）
5. スクリプト実行の確認: 最初のアプリアクセス後に、work-tmp/debug/latest/backend.log を再度確認してエラーがないか調べます
6. work-tmp/debug/latest/backend.log と work-tmp/debug/latest/frontend.log を調べてログを監視します
7. コードを編集します - 変更はホットリロードによって自動的に適用されます
8. ログでデバッグ出力を確認します

簡単なエラーチェック:

# Backend errors
rg -i "error|exception" work-tmp/debug/latest/backend.log

# Frontend console errors
rg -i "error" work-tmp/debug/latest/frontend.log

スクリーンショットとテスト用の一時的な Playwright スクリプト

スクリーンショットや自動 UI 操作を伴う高度なデバッグ向けです。

簡単な方法: Playwright CLI

簡単なスクリーンショットや操作には、@playwright/cli（フロントエンドの devDependencies で利用可能）を使用します:

cd frontend
STREAMLIT_APP_URL=http://localhost:3001
yarn playwright-cli open "$STREAMLIT_APP_URL"
yarn playwright-cli screenshot --filename ../work-tmp/debug/screenshot.png --full-page
yarn playwright-cli close

その他のコマンド（snapshot、click、fill など）については https://github.com/microsoft/playwright-cli を参照してください。

カスタムスクリプト

複雑な操作には、work-tmp/debug/ に一時的な Playwright スクリプトを作成します:

# work-tmp/debug/debug_screenshot.py
"""Temporary Playwright script for debugging - run against make debug."""
import os
from playwright.sync_api import sync_playwright, expect

from e2e_playwright.shared.app_utils import get_text_input, click_button
from e2e_playwright.conftest import wait_for_app_loaded, wait_for_app_run


def main():
    app_url = os.environ.get("STREAMLIT_APP_URL", "http://localhost:3001")
    with sync_playwright() as p:
        browser = p.chromium.launch(headless=True)
        page = browser.new_page(viewport={"width": 1280, "height": 720})

        # Connect to app started with `make debug`
        page.goto(app_url)
        wait_for_app_loaded(page)

        # Interact with the app
        text_input = get_text_input(page, "Name")
        text_input.fill("Test User")
        click_button(page, "Submit")
        wait_for_app_run(page)

        # Verify and screenshot
        expect(page.get_by_text("Hello, Test User")).to_be_visible()
        page.screenshot(path="work-tmp/debug/debug_screenshot.png", full_page=True)
        print("Screenshot saved to work-tmp/debug/debug_screenshot.png")

        browser.close()


if __name__ == "__main__":
    main()

一時的なスクリプトの実行

まず make debug <app.py> が実行中であることを確認してください（必要であればバックグラウンドタスクで起動します）。make debug セッションがデフォルト以外のポートを使用している場合は、それに応じて STREAMLIT_APP_URL を設定してから、Playwright スクリプトを実行します:

STREAMLIT_APP_URL=http://localhost:3001 \
PYTHONPATH=. uv run python work-tmp/debug/debug_screenshot.py

これは、すべての依存関係（playwright など）を含む uv 管理の環境を使用し、パスの操作なしで e2e_playwright をインポート可能にします。

e2e_playwright で利用可能なユーティリティ

要素ロケーターと操作 (e2e_playwright.shared.app_utils): get_text_input()、get_button()、click_button()、get_checkbox() などのヘルパーを提供します。

同期 (e2e_playwright.conftest):

• wait_for_app_loaded(page) - 初期読み込みを待機します
• wait_for_app_run(page) - 操作後のスクリプト実行を待機します
• wait_until(page, fn, timeout) - 条件が真になるまでポーリングします

Playwright API リファレンス: https://playwright.dev/python/docs/api/class-playwright

スクリーンショットのベストプラクティス

# Full page screenshot
page.screenshot(path="work-tmp/debug/full.png", full_page=True)

# Element screenshot
element = page.get_by_test_id("stDataFrame")
element.screenshot(path="work-tmp/debug/dataframe.png")

トラブルシューティング

ポートが既に使用されている / 複数のセッション:

• make debug は空いているフロントエンドポート（通常は 3001-3100 の範囲）を自動的に選択するため、複数のデバッグセッションを同時に実行できます。
• フロントエンドポート 3000 は、手動の make frontend-dev セッション用に予約されています。
• 特定のフロントエンドポートをどうしても使用する必要がある場合は、VITE_PORT=3002 make debug <app.py> で固定できます（最終手段）。

ホットリロードが機能しない:

• バックエンド: 監視されるのはアプリスクリプトのみです。lib/streamlit/ への変更には make debug の再起動が必要です。
• フロントエンド: Vite のエラーについては work-tmp/debug/latest/frontend.log を確認してください。TypeScript のエラーは HMR を壊す可能性があります。

Playwright スクリプトが接続に失敗する:

• make debug が実行中で正常であることを確認してください
• 表示された App URL がブラウザーでアクセス可能であることを確認してください
• page.goto() の後に wait_for_app_loaded(page) が呼び出されていることを確認してください

クリーンアップ

デバッグが完了したら、work-tmp/debug/ から一時スクリプトとスクリーンショットを削除してください。

関連スキル

• understanding-streamlit-architecture skill: クロスレイヤーの問題をデバッグする際に、バックエンド / フロントエンドの内部をより深く理解するために