asc-shots-pipeline

asc スクリーンショットパイプライン（xcodebuild -> AXe -> frame -> asc）

アプリを Xcode CLI ツールでビルドして起動し、AXe で UI を操作して、asc でスクリーンショットをアップロードする、エージェント主導のスクリーンショットワークフローでは、このスキルを使用してください。

現在の対応範囲

• 現在実装済み：ビルド／実行、AXe によるプランのキャプチャ、フレーム合成、アップロード。
• デバイスの検出は asc screenshots list-frame-devices に組み込まれています。
• asc CLI のローカルスクリーンショット自動化コマンドは実験的な機能です。
• フレーミングの出力を決定的にするため、Koubou 0.20.0 に固定しています。
• フィードバック／問題報告：https://github.com/rorkai/App-Store-Connect-CLI/issues/new/choose

デフォルト

• 設定ファイル：.asc/shots.settings.json
• キャプチャプラン：.asc/screenshots.json
• 元のスクリーンショットのディレクトリ：./screenshots/raw
• フレーム付きスクリーンショットのディレクトリ：./screenshots/framed
• デフォルトのフレームデバイス：iphone-air

1) まず設定 JSON を作成する

.asc/shots.settings.json を作成または更新します。

{
  "version": 1,
  "app": {
    "bundle_id": "com.example.app",
    "project": "MyApp.xcodeproj",
    "scheme": "MyApp",
    "simulator_udid": "booted"
  },
  "paths": {
    "plan": ".asc/screenshots.json",
    "raw_dir": "./screenshots/raw",
    "framed_dir": "./screenshots/framed"
  },
  "pipeline": {
    "frame_enabled": true,
    "upload_enabled": false
  },
  "upload": {
    "version_localization_id": "",
    "device_type": "IPHONE_65",
    "source_dir": "./screenshots/framed"
  }
}

フレーミングを意図的に省略する場合は、次のように設定します。

• "frame_enabled": false
• "upload.source_dir": "./screenshots/raw"

2) シミュレーターでアプリをビルドして実行する

ビルド、インストール、起動には Xcode CLI を使用します。

xcrun simctl boot "$UDID" || true

xcodebuild \
  -project "MyApp.xcodeproj" \
  -scheme "MyApp" \
  -configuration Debug \
  -destination "platform=iOS Simulator,id=$UDID" \
  -derivedDataPath ".build/DerivedData" \
  build

xcrun simctl install "$UDID" ".build/DerivedData/Build/Products/Debug-iphonesimulator/MyApp.app"
xcrun simctl launch "$UDID" "com.example.app"

アプリバンドルのパスがデフォルトの場所と異なる場合は、xcodebuild -showBuildSettings を使用してください。

3) AXe（または asc screenshots run）でスクリーンショットをキャプチャする

プランに基づくキャプチャを推奨します。

asc screenshots run --plan ".asc/screenshots.json" --udid "$UDID" --output json

プラン作成時に便利な AXe の基本機能：

axe describe-ui --udid "$UDID"
axe tap --id "search_field" --udid "$UDID"
axe type "wwdc" --udid "$UDID"
axe screenshot --output "./screenshots/raw/home.png" --udid "$UDID"

.asc/screenshots.json の最小限の例：

{
  "version": 1,
  "app": {
    "bundle_id": "com.example.app",
    "udid": "booted",
    "output_dir": "./screenshots/raw"
  },
  "steps": [
    { "action": "launch" },
    { "action": "wait", "duration_ms": 800 },
    { "action": "screenshot", "name": "home" }
  ]
}

4) asc screenshots frame でスクリーンショットにフレームを追加する

asc CLI では、フレーミングに Koubou 0.20.0 を使用するよう固定しています。 フレーミング手順を実行する前に、インストールして確認してください。

pip install koubou==0.20.0
kou --version  # expect 0.20.0
# After upgrading from 0.18.x, or if Koubou reports missing device frames,
# run once with network access:
kou setup-frames

まず、対応しているフレームデバイスの値を一覧表示します。

asc screenshots list-frame-devices --output json

スクリーンショット 1 枚にフレームを追加します（デフォルトは iphone-air）。

asc screenshots frame \
  --input "./screenshots/raw/home.png" \
  --output-dir "./screenshots/framed" \
  --device "iphone-air" \
  --output json

対応する --device の値：

• iPhone：iphone-air（デフォルト）、iphone-17-pro、iphone-17-pro-max、iphone-16e、iphone-17
• iPad：ipad-pro-13、ipad-pro-11、ipad-air-13、ipad-air-11、ipad-mini
• その他：mac、watch-series-11、watch-ultra-3、apple-tv

5) asc でスクリーンショットをアップロードする

アップロード前に、成果物を生成して確認します。

asc screenshots review-generate --framed-dir "./screenshots/framed" --output-dir "./screenshots/review"
asc screenshots review-open --output-dir "./screenshots/review"
asc screenshots review-approve --all-ready --output-dir "./screenshots/review"

複数のロケールに対応するセットを確認してからアップロードする場合は、アップロード前に既存のリモートスクリーンショット数を反映できる、プラン／適用フローを推奨します。

asc screenshots plan --app "APP_ID" --version "1.2.3" --review-output-dir "./screenshots/review" --output json
asc screenshots apply --app "APP_ID" --version "1.2.3" --review-output-dir "./screenshots/review" --confirm --output json

設定済みのソースディレクトリからアップロードします（フレーミングが有効な場合のデフォルトは ./screenshots/framed）。

asc screenshots upload \
  --version-localization "LOC_ID" \
  --path "./screenshots/framed" \
  --device-type "IPHONE_65" \
  --output json

必要に応じて、アップロード前に一覧表示または検証します。

asc screenshots sizes --output table
asc screenshots list --version-localization "LOC_ID" --output table

再アップロードせずに、アップロード済みセットの順序を変更します。--ids には、セット内のすべてのスクリーンショットを新しい順序で 1 回ずつ指定する必要があります。コマンドがセットを読み取った後にスクリーンショットが追加されると、App Store Connect は更新を拒否し、更新前の順序を維持します。セットを再度一覧表示して、コマンドを再実行してください。他のユーザーが行った順序のみの変更は検出されず、上書きされます。

asc localizations screenshot-sets list --localization-id "LOC_ID" --include appScreenshots
asc screenshots list --set-id "SET_ID" --output table
asc screenshots reorder --set-id "SET_ID" --ids "THIRD_ID,FIRST_ID,SECOND_ID"

エージェントの動作

• コマンドを実行する前に、必ず --help で正確なフラグを確認してください。
• スクリーンショット関連のコマンドは急速に変化しているため、asc screenshots --help でコマンドパスを再確認してください。
• 出力は決定的に保ち、機械処理の手順では JSON をデフォルトにしてください。
• フレームデバイスを選択する前に、asc screenshots list-frame-devices --output json を実行することを推奨します。
• アップロード前に、スクリーンショットファイルが存在することを確認してください。
• アップロード済みセットの順序変更には asc screenshots reorder を使用してください。順序変更のためにスクリーンショットを削除して再アップロードしてはいけません。
• 明示的なロングフラグ（--app、--output、--version-localization など）を使用してください。
• スクリーンショットのローカル自動化は実験的な機能として扱い、ユーザー向けの引き継ぎメモでその旨を明記してください。
• 既存のリモートスクリーンショットを考慮した追加上限のガードが必要な場合は、確認済みのバッチに asc screenshots plan／asc screenshots apply を使用してください。
• バージョンエラーでフレーミングに失敗した場合は、固定バージョンの Koubou を再インストールしてください：pip install koubou==0.20.0
• デバイスフレームが見つからずフレーミングに失敗した場合は、ネットワークに接続できる状態で kou setup-frames を 1 回実行してください。

6) 複数ロケールでのキャプチャ（任意）

ローカライズには xcrun simctl launch ... -e AppleLanguages を使用しないでください。 -e は環境変数のパターンであり、アプリの言語を確実に切り替えられません。

このパイプラインでは、UDID ごとにシミュレーター全体のロケール設定を使用します。これは、 アプリを内部で再起動する asc screenshots capture で機能します。

# Map each locale to a dedicated simulator UDID.
# (Create these simulators once with `xcrun simctl create`.)
declare -A LOCALE_UDID=(
  ["en-US"]="UDID_EN_US"
  ["de-DE"]="UDID_DE_DE"
  ["fr-FR"]="UDID_FR_FR"
  ["ja-JP"]="UDID_JA_JP"
)

set_simulator_locale() {
  local UDID="$1"
  local LOCALE="$2"            # e.g. de-DE
  local LANG="${LOCALE%%-*}"   # de
  local APPLE_LOCALE="${LOCALE/-/_}" # de_DE

  xcrun simctl boot "$UDID" || true
  xcrun simctl spawn "$UDID" defaults write NSGlobalDomain AppleLanguages -array "$LANG"
  xcrun simctl spawn "$UDID" defaults write NSGlobalDomain AppleLocale -string "$APPLE_LOCALE"
}

for LOCALE in "${!LOCALE_UDID[@]}"; do
  UDID="${LOCALE_UDID[$LOCALE]}"
  echo "Capturing $LOCALE on $UDID..."
  set_simulator_locale "$UDID" "$LOCALE"

  xcrun simctl terminate "$UDID" "com.example.app" || true
  asc screenshots capture \
    --bundle-id "com.example.app" \
    --name "home" \
    --udid "$UDID" \
    --output-dir "./screenshots/raw/$LOCALE" \
    --output json
done

手動で起動する場合（asc screenshots capture を使わない場合）は、アプリの起動引数を使用してください。

xcrun simctl launch "$UDID" "com.example.app" -AppleLanguages "(de)" -AppleLocale "de_DE"

7) 並列実行による高速化

シミュレーターの UDID ごとに 1 つのロケールを並列実行します。

#!/bin/bash
# parallel-capture.sh

declare -A LOCALE_UDID=(
  ["en-US"]="UDID_EN_US"
  ["de-DE"]="UDID_DE_DE"
  ["fr-FR"]="UDID_FR_FR"
  ["ja-JP"]="UDID_JA_JP"
)

capture_locale() {
  local LOCALE="$1"
  local UDID="$2"
  local LANG="${LOCALE%%-*}"
  local APPLE_LOCALE="${LOCALE/-/_}"

  echo "Starting $LOCALE on $UDID"
  xcrun simctl boot "$UDID" || true
  xcrun simctl spawn "$UDID" defaults write NSGlobalDomain AppleLanguages -array "$LANG"
  xcrun simctl spawn "$UDID" defaults write NSGlobalDomain AppleLocale -string "$APPLE_LOCALE"
  xcrun simctl terminate "$UDID" "com.example.app" || true

  asc screenshots capture \
    --bundle-id "com.example.app" \
    --name "home" \
    --udid "$UDID" \
    --output-dir "./screenshots/raw/$LOCALE" \
    --output json

  echo "Completed $LOCALE"
}

for LOCALE in "${!LOCALE_UDID[@]}"; do
  capture_locale "$LOCALE" "${LOCALE_UDID[$LOCALE]}" &
done

wait
echo "All captures done. Now framing..."

または、locale:udid のペアと xargs を使用します。

printf "%s\n" \
  "en-US:UDID_EN_US" \
  "de-DE:UDID_DE_DE" \
  "fr-FR:UDID_FR_FR" \
  "ja-JP:UDID_JA_JP" | xargs -P 4 -I {} bash -c '
    PAIR="{}"
    LOCALE="${PAIR%%:*}"
    UDID="${PAIR##*:}"
    LANG="${LOCALE%%-*}"
    APPLE_LOCALE="${LOCALE/-/_}"
    xcrun simctl boot "$UDID" || true
    xcrun simctl spawn "$UDID" defaults write NSGlobalDomain AppleLanguages -array "$LANG"
    xcrun simctl spawn "$UDID" defaults write NSGlobalDomain AppleLocale -string "$APPLE_LOCALE"
    xcrun simctl terminate "$UDID" "com.example.app" || true
    asc screenshots capture --bundle-id "com.example.app" --name "home" --udid "$UDID" --output-dir "./screenshots/raw/$LOCALE" --output json
  '

8) 複数ロケールのパイプライン全体の例

#!/bin/bash
# full-pipeline-multi-locale.sh

declare -A LOCALE_UDID=(
  ["en-US"]="UDID_EN_US"
  ["de-DE"]="UDID_DE_DE"
  ["fr-FR"]="UDID_FR_FR"
  ["es-ES"]="UDID_ES_ES"
  ["ja-JP"]="UDID_JA_JP"
)

DEVICE="iphone-air"
RAW_DIR="./screenshots/raw"
FRAMED_DIR="./screenshots/framed"

# Step 1: Parallel capture with per-simulator locale defaults
for LOCALE in "${!LOCALE_UDID[@]}"; do
  (
    UDID="${LOCALE_UDID[$LOCALE]}"
    LANG="${LOCALE%%-*}"
    APPLE_LOCALE="${LOCALE/-/_}"

    xcrun simctl boot "$UDID" || true
    xcrun simctl spawn "$UDID" defaults write NSGlobalDomain AppleLanguages -array "$LANG"
    xcrun simctl spawn "$UDID" defaults write NSGlobalDomain AppleLocale -string "$APPLE_LOCALE"
    xcrun simctl terminate "$UDID" "com.example.app" || true

    asc screenshots capture \
      --bundle-id "com.example.app" \
      --name "home" \
      --udid "$UDID" \
      --output-dir "$RAW_DIR/$LOCALE" \
      --output json
    echo "Captured $LOCALE"
  ) &
done
wait

# Step 2: Parallel framing
for LOCALE in "${!LOCALE_UDID[@]}"; do
  (
    asc screenshots frame \
      --input "$RAW_DIR/$LOCALE/home.png" \
      --output-dir "$FRAMED_DIR/$LOCALE" \
      --device "$DEVICE" \
      --output json
    echo "Framed $LOCALE"
  ) &
done
wait

# Step 3: Generate review (single run, aggregates all locales)
asc screenshots review-generate \
  --framed-dir "$FRAMED_DIR" \
  --output-dir "./screenshots/review"

# Step 4: Upload (run per locale if needed)
for LOCALE in "${!LOCALE_UDID[@]}"; do
  asc screenshots upload \
    --version-localization "LOC_ID_FOR_$LOCALE" \
    --path "$FRAMED_DIR/$LOCALE" \
    --device-type "IPHONE_65" \
    --output json
done