push-notification-test

name	push-notification-test
description	推播通知測試專屬流程，覆蓋 APNs（iOS）/ FCM（Android）/ Web Push 三大平台。驗證送達率、點擊行為（cold start / warm / background）、Deep link 跳轉、權限拒絕後 fallback、字級放大不破版、batch 大量推播效能。當使用者提到「推播測試 / push notification / APNs / FCM / Deep link / 通知點擊 / 推播權限 / 推播送達率 / silent push / 通知 Action button」時觸發。配套：test-master（規劃 push TC）、test-automation（push UI test）、a11y-audit（推播在 lock screen 的 a11y）、bug-report（push 相關 bug）。
disable-model-invocation	false
allowed-tools	Read, Grep, Glob, Write, Edit, Bash
argument-hint	[平台 ios|android|web] [--scenario=delivery|click|deeplink|permission|all]

push-notification-test

⚙️ 執行前先讀 modules/config-loader.md。

為什麼推播測試容易出包

推播流程跨 4 個系統：

1. 你的後端 → 發送
2. APNs / FCM → 路由 + 鎖屏渲染
3. OS（iOS / Android） → 通知中心 / 權限
4. App → 啟動 / Deep link / 狀態還原

任何一段壞，使用者看不到通知。 且只有真實裝置才能完整測試（Simulator 不支援推播）。

適用場景

• ✅ 有用 push 的 App（行銷推播 / 訂單通知 / 即時訊息 / 提醒）
• ✅ 改 push payload schema 前（容易壞 Deep link）
• ✅ 升 iOS / Android 主版本後（權限機制常變）
• ✅ 改 App 圖示 / 名稱後（通知 banner 可能跑掉）

不適用場景

• ❌ App 完全不用推播
• ❌ 純後端發送邏輯 — 用 tc-to-pytest 測 API

8 大測試場景

1. 送達率測試（Delivery）

測試	期望
一般推播（App 在 background）	10 秒內顯示在通知中心
App 在 foreground	UI 內 in-app 提示 + 不顯系統 banner
App killed / 重啟手機	仍能收到（除非禁止）
弱網 / 飛航模式	開啟後立刻補送
Silent push（content-available）	不顯通知但喚醒 App

2. 點擊行為（Click handling）

各狀態下點擊推播：

狀態	期望行為
Cold start（App 完全沒在跑）	啟動 App → 直接跳目標頁
Warm（App 在 background）	回到 App → 跳目標頁
Active（App 在 foreground）	直接跳目標頁
Locked（鎖屏）	解鎖後跳目標頁

3. Deep link 跳轉

對每種 payload type：

{
  "aps": { "alert": "新訂單！", "category": "ORDER" },
  "deep_link": "myapp://orders/12345",
  "campaign_id": "summer-sale"
}

驗證：

• myapp://orders/12345 → 正確跳到訂單詳情頁
• 訂單 ID 解析正確
• 已登出狀態 → 先去登入 → 登入後跳目標
• 訂單已刪除 → 跳列表 + 提示「訂單不存在」

4. 權限處理

場景	期望
首次 App 啟動	在合適時機（不是一啟動就問）跳權限對話框
使用者「不允許」	in-app 引導去設定開啟
使用者後來開啟	App 偵測到 + 自動重新註冊 token
iOS 15+ Provisional auth	安靜送達，使用者第一次看到後選擇

5. Action buttons

豐富推播 (rich push):

• 訂單通知含「查看」/「忽略」按鈕
• 訊息推播含「回覆」/「標已讀」按鈕

驗證：

• 按鈕顯示正確（label / icon）
• 點擊正確 routing
• 不啟動 App 即可處理（Notification Service Extension）

6. 字級放大不破版

推播在鎖屏顯示時：

• iOS Dynamic Type 最大 → title 不截斷或要明顯標 ...
• Android 字型大小最大 → 同上
• emoji 在所有字級下大小一致

7. Localization

推播 title / body 在不同 locale 下：

• 翻譯正確（用伺服器端翻譯或 loc-key + APNs localization）
• 字串長度不爆 banner

→ 配合 localization-test skill。

8. 大批推播效能

行銷推播 send 100 萬人：

• 後端送出時間 < N 分鐘
• APNs / FCM 回應 throttle 處理
• App 重啟 (cold) 不卡 → 必須在主執行緒外處理

執行流程

Phase 1: 設定環境

# iOS
APNs: 用 development cert (sandbox) / production cert
測試裝置: 真實裝置（必）

# Android
FCM: server key + sender id
測試裝置: 真實 / emulator with Google Play Services

# 工具
- Postman + push templates
- Apple Push Notification Tool (Pusher)
- Firebase Console
- Knuff (mac, free)

Phase 2: 生成測試 payload

對每個情境生 payload + 跑送達工具：

# 用 curl + APNs
curl -v -d '{"aps":{"alert":"Test"},"deep_link":"myapp://test"}' \
  --http2 --cert apns-cert.pem \
  https://api.development.push.apple.com/3/device/<device-token>

Phase 3: 自動化 + 人工檢查

場景	可自動化	需人工
Deep link 解析	✅ Unit test	推播觸發要人
Payload schema	✅ Contract test	-
字級放大 banner	❌	✅ 截圖比對
鎖屏 a11y	❌	✅ VoiceOver 讀通知

混合：可自動化的進 CI，人工的列 checklist。

Phase 4: 監控指標

上線後 dashboard 看：

• 送達率（>95% 健康）
• 點擊率（CTR）
• Permission grant rate
• token registration success rate

⚠️ 安全護欄

• ❌ 推播測試不發給真實使用者（用 dev token 隊伍）
• ✅ Production cert 嚴格 IAM 控制
• ⚠️ Silent push 不能用於跟蹤使用者（隱私政策合規）

設定依賴

設定 Key	用途	預設
push_notification.platforms	啟用平台	[ios, android]
push_notification.test_devices	dev token 清單	[]
push_notification.deep_link_scheme	App URL scheme	""
push_notification.payload_templates_dir	payload 範本目錄	tests/push/

範例

詳見 examples.md