VM Lab
タスクにクリーンなmacOS VMが必要な場合に使用します。GUI自動化、TCCプロンプト、スクリーンショットキャプチャ、クリック、タイピング、パフォーマンス、またはPeekabooライクなツールの「双方向検証」をテストします。
コアアイデア:テスト対象のツールをゲスト内で実行しますが、Parallelsのスクリーンショットとホスト側の観察を使用して、ゲストの外部から検証します。自分が所有していないアプリは閉じないでください。
安全ルール
- VMスナップショットは消耗品として扱い、ホストは消耗品として扱わないでください。
- シークレットを出力しないでください。
opが必要な場合は、1Passwordスキルに従い、tmux内でのみ実行してください。 - 自分で作成した新しいアプリウィンドウ(TextEdit、ローカルHTMLテストページ、または小さなテストアプリ)を優先してください。
/tmp下の一時的なスクリーンショット以外、ホストの状態を変更しないでください。- VM内のgitリポジトリには、HTTPSリモートと通常のブランチ規律を使用してください。
VMディスカバリ
VMを一覧表示:
prlctl list --all
VMのステータス/IPを取得:
prlctl list --info "macOS Tahoe"
Peterとしてゲストコマンドを実行:
prlctl exec "macOS Tahoe" \
'sudo -u steipete -H /bin/zsh -lc '\''source ~/.zprofile 2>/dev/null || true; uname -a'\'''
独立したホスト側スクリーンショットをキャプチャ:
prlctl capture "macOS Tahoe" --file /tmp/vm-reference.png
sips -g pixelWidth -g pixelHeight /tmp/vm-reference.png
TCC / GUI属性
macOSの画面収録とアクセシビリティでは、責任プロセスが重要です。
prlctl execはヘッドレスであり、有用な画面収録属性を生成できない場合があります。- 画面収録が関係する場合は、ゲスト内の可視のターミナルアプリからテストコマンドを起動してください。
- Ghosttyがインストールされていれば、GUIターミナルとして機能します。
- 最初のキャプチャが失敗した後は、「システム設定 > プライバシーとセキュリティ > 画面収録とシステムオーディオ収録」を確認してください。
prlctl exec経由で実行されるpermissions statusは、Ghosttyが許可された後でも画面収録がfalseと報告する場合があります。Ghosttyからキャプチャを再実行して画面収録を検証してください。
画面収録ペインを開く:
prlctl exec "macOS Tahoe" \
'sudo -u steipete -H open "x-apple.systempreferences:com.apple.preference.security?Privacy_ScreenCapture"'
Ghosttyを開く:
prlctl exec "macOS Tahoe" 'sudo -u steipete -H open -a Ghostty'
Ghosttyを通じてコマンドを実行する
最適なパス:prlctl exec でゲストスクリプトを作成し、Ghosttyを開いてフォーカスし、短いランチャーパスのみを可視のターミナルに入力します。
ゲストスクリプトのパターン:
prlctl exec "macOS Tahoe" 'sudo -u steipete -H /bin/zsh -lc '\''cat > /tmp/run-vm-lab.zsh <<EOF
#!/bin/zsh
source ~/.zprofile 2>/dev/null || true
cd ~/Projects/Peekaboo || exit 1
Apps/CLI/.build/debug/peekaboo image --path /tmp/peekaboo-vm.png --json
rc=$?
echo "EXIT:$rc"
[ -f /tmp/peekaboo-vm.png ] && sips -g pixelWidth -g pixelHeight /tmp/peekaboo-vm.png
echo "Press return to close..."
read _
exit $rc
EOF
chmod +x /tmp/run-vm-lab.zsh
ln -sf /tmp/run-vm-lab.zsh /tmp/r
open -a Ghostty'\'''
次に、ランチャーをGhosttyのホームディレクトリにリンクし、scripts/parallels_type.py で ./r と入力します。これにより、Parallelsのキーインジェクションにおける信頼性の低いパス文字を回避できます。
prlctl exec "macOS Tahoe" \
"sudo -u steipete -H /bin/zsh -lc 'ln -sf /tmp/run-vm-lab.zsh ~/r'"
python3 skills/vm-lab/scripts/parallels_type.py "macOS Tahoe" $'./r\n'
長いコマンドのタイピングは避けてください。Parallelsのキーインジェクションは独自のキーコードテーブルを使用し、レイアウトの影響を受けやすい可能性があります。
既知の落とし穴
- macOSのクリップボードAPIは
prlctl execから失敗する可能性があります。pbcopy、AppleScriptクリップボード、Peekabooのペーストはすべてヘッドレスゲストコンテキストで失敗する可能性があります。 open -na Ghostty.app --args -e ...は、macOS上で既存のGhosttyウィンドウをフォーカスするだけの場合があります。コマンドが実行されるとは想定しないでください。prlctl execはゲストシェルを通じてargvを再結合する場合があります。複雑なペイロードの場合は、完全にシェルクォートされたコマンド文字列を1つ渡すか、小さなPythonライターでファイルを作成してください。- Parallelsの
send-key-event --keyは、macOSの仮想キーコードではなく、Parallelsのキー値を使用します。 - 通常のタイピングでは、
--eventなしでprlctl send-key-event <vm> --key <key>を送信してください。明示的なpress/releaseは繰り返したり固着したりする可能性があります。Returnは例外で、pressの後にreleaseを使用してください。 - 多くの別々の
send-key-eventプロセスよりも、1つのprlctl send-key-event --jsonバッチを優先してください。個別の呼び出しはフォーカス/レイテンシの影響でずれる可能性があります。 PRL_KEY_ENTER = 36、PRL_KEY_SLASH = 61、PRL_KEY_R = 27、PRL_KEY_T = 28、PRL_KEY_M = 58、PRL_KEY_P = 33を使用してください。- キーストロークが文字化けを生成する場合は、Returnを送信して行をクリアし、より短いランチャーを作成してから再試行してください。
- Peekabooの権限プローブが画面収録不足でハングし、
SWIFT TASK CONTINUATION MISUSEを出力する場合は、製品バグとして記録してください。VMハーネスと混同しないでください。
双方向検証
各GUIアクションについて、2つの独立したシグナルで検証します:
- テスト対象ツールの出力:JSON、スクリーンショットファイル、AX結果、またはアプリの状態。
- 外部検証器:
prlctl capture、ホスト側の画像検査、ゲスト内のファイル内容、またはプロセス/ウィンドウの状態。
例:
- スクリーンショット:Peekabooの画像の寸法/内容を
prlctl captureと比較します。 - クリック:Peekabooを使用してテストボタンをクリックし、ゲストアプリの状態とホストのスクリーンショットの両方を検証します。
- タイピング:Peekabooを使用して制御されたテキストフィールドに入力し、AX値とホストのスクリーンショットの両方を検証します。
- パフォーマンス:コマンドを
/usr/bin/time -pでラップします。コールド/ウォームランを繰り返します。出力は/tmpに保持します。
Peekaboo VMベースライン
ゲスト内:
cd ~/Projects/Peekaboo
git pull --recurse-submodules
swift build --package-path Apps/CLI
Apps/CLI/.build/debug/peekaboo --version
Apps/CLI/.build/debug/peekaboo permissions status --json
ホスト側のリファレンスキャプチャ:
prlctl capture "macOS Tahoe" --file /tmp/vm-prlctl-reference.png
Ghosttyを通じたゲスト側のPeekabooキャプチャ:
/tmp/r
比較:
prlctl exec "macOS Tahoe" \
'sudo -u steipete -H /bin/zsh -lc '\''sips -g pixelWidth -g pixelHeight /tmp/peekaboo-vm.png'\'''
sips -g pixelWidth -g pixelHeight /tmp/vm-prlctl-reference.png
報告
引き継ぐ際は、以下のみを含めてください:
- VM名とOSビルド。
- テストしたリポジトリのコミット。
- 権限の状態。
- 成功/失敗したコマンド。
- 独立した検証器の結果。
- 発見された製品バグ。