🎥见于行
* 观看演示视频 - 看Moc Bridge如何简化商店应用测试
为什么使用这个软件包?
测试 Shopify 嵌入式应用程序难度 :
- {\fn黑体\fs22\bord1\shad0\3aHBE\4aH00\fscx67\fscy66\2cHFFFFFF\3cH808080}店员需要2FA和Captchas
- QQ Playwright/ 自定义工具无法绕过安全
- Chrome DevTools MCP 无法与您的嵌入式 Shopify 应用程序交互
- CI/CD管道需要互联网和证书
- 实际管理员的手工测试缓慢且不可靠
这个软件包可以解决所有问题:
- * 不需要卡布查、2FA或真正的Shopify账户
- QQ 完全 Playwright 和自动化支持
- QQ Chrome MCP 和 DevTools 兼容性
- 离线工程和CI/CD管道
- * 进行综合测试的真正数据库集成
API 支持
核心特征
| 特性 | 状态 | 页:1 |
|---|---|---|
| iFrame 嵌入 | 获支持 | 带有 Polaris 样式的完整管理框架 |
| 会话符号 | 获支持 | shopify.idToken() |
| 模拟环境探测 | 获支持 | 自动装入模拟 App 桥 |
应用桥 API
| API 密码 | 状态 | 页:1 |
|---|---|---|
shopify.modal | 获支持 | show(), (中文(简体) ), hide(), (中文(简体) ), toggle() |
shopify.saveBar | 获支持 | show(), (中文(简体) ), hide(), (中文(简体) ), toggle() |
shopify.loading | 获支持 | loading(boolean) |
shopify.toast | 获支持 | show(message, options) |
shopify.idToken | 获支持 | 返回有效的 JWT |
shopify.config | 获支持 | apiKey, (中文(简体) ), shop, (中文(简体) ), locale |
shopify.environment | 获支持 | embedded, (中文(简体) ), mobile, (中文(简体) ), pos |
shopify.user | 获支持 | 返回模拟用户对象 |
shopify.scopes | 🔶 Stu | 返回模拟数据 |
shopify.resourcePicker | 🔶 Stu | 返回空数组 |
shopify.picker | 🔶 Stu | 返回空选择 |
shopify.scanner | 🔶 Stu | 返回模拟扫描数据 |
shopify.pos | 🔶 Stu | 有模拟数据的 Cart API |
shopify.intents | 🔶 Stu | invoke(), (中文(简体) ), register() |
shopify.webVitals | 🔶 Stu | 只召回注册 |
shopify.support | 🔶 Stu | 只召回注册 |
shopify.reviews | 🔶 Stu | 回归成功 |
shopify.app | 🔶 Stu | 返回空扩展 |
| 经认证的获取 | 获支持 | 模拟、代理或直接模式 |
| 导航 | 未执行 | |
| 打印 | 未执行 | |
| 份额 | 未执行 |
Web 组件
| 构成部分 | 状态 | 页:1 |
|---|---|---|
<ui-modal> | 获支持 | 与 <ui-title-bar> 支助 |
<ui-save-bar> | 获支持 | 与 data-save-bar 窗体整合 |
<ui-nav-menu> | 获支持 | 在管理边栏显示 |
<ui-title-bar> | 获支持 | 内部模式 |
<s-app-window> | 未执行 |
图例: QQ 支持的 Stub (返回模拟数据) QQ 未执行
* 安装
npm install @getverdict/mock-bridge --save-dev
# or
yarn add @getverdict/mock-bridge --dev
# or
pnpm add @getverdict/mock-bridge --save-dev
QQ 快速启动(2个命令)
# 1. Install the package
npm install @getverdict/mock-bridge --save-dev
# 2. Start the mock (just provide your app URL)
npx @getverdict/mock-bridge http://localhost:3000
就这样! 您的应用软件现在运行在模拟的商店管理器上 http://localhost:3080
QQ 快速启动指南
第1步: 启动 Moc 服务器
备选案文A: " 一次性启动 " (建议)
# Simplest - just provide your app URL
npx @getverdict/mock-bridge http://localhost:3000
# Auto-detects client ID from SHOPIFY_API_KEY environment variable
# Auto-detects common app paths and configurations
选项B:配置文件
# Generate a config file
npx @getverdict/mock-bridge init
# Edit the generated mock.config.js, then run:
npx @getverdict/mock-bridge
# Add to package.json scripts for easy access
{
"scripts": {
"dev": "next dev",
"mock:admin": "mock-bridge http://localhost:3000",
"dev:mock": "concurrently \"npm run dev\" \"npm run mock:admin\""
}
}
备选C:程序化的API
如果您需要更多的控制, 您仍然可以使用程序 API :
// scripts/start-mock-admin.js
const { MockShopifyAdminServer } = require("@verdict/mock-bridge");
async function startMockAdmin() {
const server = new MockShopifyAdminServer({
appUrl: "http://localhost:3000",
clientId: process.env.SHOPIFY_API_KEY,
clientSecret: "mock-secret-12345",
port: 3080,
debug: true,
});
await server.start();
console.log("🎉 Mock Shopify Admin ready at http://localhost:3080");
}
startMockAdmin().catch(console.error);
第2步:前端整合
启用您的应用程序来检测和使用模拟环境 :
备选案文A:自动检测(建议)
替换您的 App 桥脚本装入 :
<!-- Before: Direct CDN loading -->
<script src="https://cdn.shopify.com/shopifycloud/app-bridge.js"></script>
<!-- After: Smart loading with mock support -->
<script>
// Check if we're in a mock environment
const urlParams = new URLSearchParams(window.location.search);
const isEmbedded = urlParams.get("embedded") === "1";
const host = urlParams.get("host");
let isMockEnvironment = false;
// Detect mock environment from URL parameters
if (isEmbedded && host) {
try {
const decodedHost = atob(host);
if (
decodedHost.includes("localhost") ||
decodedHost.includes("mock") ||
window.location.hostname === "localhost"
) {
isMockEnvironment = true;
}
} catch (e) {
// Ignore decode errors
}
}
// Load appropriate App Bridge
if (isMockEnvironment) {
console.log("Loading Mock App Bridge");
const script = document.createElement("script");
script.src = "http://localhost:3080/app-bridge.js";
script.onerror = () => {
// Fallback to real CDN if mock fails
const fallback = document.createElement("script");
fallback.src = "https://cdn.shopify.com/shopifycloud/app-bridge.js";
document.head.appendChild(fallback);
};
document.head.appendChild(script);
} else {
console.log("Loading Real Shopify App Bridge");
const script = document.createElement("script");
script.src = "https://cdn.shopify.com/shopifycloud/app-bridge.js";
document.head.appendChild(script);
}
</script>
选项 B: 软件包工具( TypeScript)
// app.tsx or _app.tsx
import { setupAppBridge } from "@getverdict/mock-bridge/client";
useEffect(() => {
setupAppBridge({
debug: true,
onMockDetected: (mockServerUrl) => {
console.log("Mock environment detected:", mockServerUrl);
},
onShopifyDetected: () => {
console.log("Real Shopify environment detected");
},
})
.then(() => {
console.log("App Bridge loaded successfully");
})
.catch(console.error);
}, []);
第3步:后端集成
将您的后端支持模拟会话符号和真实的会话符号一起制作 :
快速集成(取代现有的 JWT 验证)
// Before: Only real Shopify tokens
import { verifyShopifyJWT } from "./your-auth";
export async function authenticate(token: string) {
const authData = await verifyShopifyJWT(token);
// ... rest of auth logic
}
// After: Support both real and mock tokens
import {
validateSessionToken,
createMockUser,
} from "@getverdict/mock-bridge/auth";
export async function authenticate(token: string) {
const authData = await validateSessionToken(token, {
shopifySecret: process.env.SHOPIFY_API_PRIVATE_KEY!,
});
if (!authData) {
throw new Error("Invalid token");
}
// Get shop from your database (same for both mock and real)
const shop = await getShopByName(authData.shopName);
if (!shop) {
throw new Error("Shop not found");
}
if (authData.isMock) {
// Mock environment - skip Shopify API calls
return {
shop,
currentUser: createMockUser({
shopName: authData.shopName,
permissions: shop.settings?.defaultStaffPermissions,
}),
isMock: true,
};
} else {
// Real environment - proceed with normal Shopify flow
const currentUser = await exchangeTokenForUser(token, shop);
return {
shop,
currentUser,
isMock: false,
};
}
}
具体框架实例
Next.js API 路由:
// pages/api/products.ts
import { validateSessionToken } from "@getverdict/mock-bridge/auth";
export default async function handler(req, res) {
const token = req.headers.authorization?.replace("Bearer ", "");
const authData = await validateSessionToken(token, {
shopifySecret: process.env.SHOPIFY_API_PRIVATE_KEY!,
});
if (!authData) {
return res.status(401).json({ error: "Unauthorized" });
}
if (authData.isMock) {
// Return mock data for testing
return res.json({
products: [
{ id: "1", title: "Mock Product 1", price: "19.99" },
{ id: "2", title: "Mock Product 2", price: "29.99" },
],
});
} else {
// Fetch real products from Shopify
const products = await fetchShopifyProducts(authData.shopName);
return res.json({ products });
}
}
Express.js Midddleware: (英语)
import {
validateSessionToken,
createMockUser,
} from "@getverdict/mock-bridge/auth";
function createAuthMiddleware() {
return async (req, res, next) => {
const token = req.headers.authorization?.replace("Bearer ", "");
const authData = await validateSessionToken(token, {
shopifySecret: process.env.SHOPIFY_API_PRIVATE_KEY!,
});
if (!authData) {
return res.status(401).json({ error: "Unauthorized" });
}
const shop = await getShopByName(authData.shopName);
req.shop = shop;
req.isMockAuth = authData.isMock;
if (authData.isMock) {
req.currentUser = createMockUser({ shopName: authData.shopName });
} else {
req.currentUser = await exchangeTokenForUser(token, shop);
}
next();
};
}
app.use("/api/*", createAuthMiddleware());
第4步:数据库设置
确保您的模拟商店在数据库中存在 :
// Add this to your database seed or setup script
async function setupMockShop() {
const mockShop = {
name: "test-shop.myshopify.com",
displayName: "Mock Test Shop",
accessToken: "mock-access-token",
active: true,
settings: {
defaultStaffPermissions: [
"read_products",
"write_products",
"read_orders",
"write_orders",
],
},
};
await createOrUpdateShop(mockShop);
console.log("Mock shop created for testing");
}
// Run during development setup
if (process.env.NODE_ENV === "development") {
setupMockShop();
}
第5步:开始发展
# Option 1: CLI command (simplest)
npx @getverdict/mock-bridge http://localhost:3000
# Option 2: Package.json scripts
npm run dev:mock
# Option 3: Separate terminals
npm run dev # Terminal 1: Your app
npm run mock:admin # Terminal 2: Mock admin
然后导航到:
- 你的应用: http://localhost:3:00
- 雾化商店管理员: http://localhost:3080 (英语)
- 您的应用程序嵌入了模拟管理员: http://localhost:3080 (自动嵌入您的应用) 互联网档案馆的存檔,存档日期2013-10-21
CLI 参考
快速命令
# Basic usage with auto-detection
npx @getverdict/mock-bridge http://localhost:3000
# If installed locally, you can use the shorter command:
# npm install @getverdict/mock-bridge --save-dev
# npx mock-bridge http://localhost:3000
# Full configuration
npx @getverdict/mock-bridge http://localhost:3000/shopify \
--client-id your-client-id \
--port 3080 \
--debug
# Using config file
npx @getverdict/mock-bridge init # Create config file
npx @getverdict/mock-bridge # Use config file
# Help and version
npx @getverdict/mock-bridge --help
npx @getverdict/mock-bridge --version
CLI 选项
| 选项 | 说明 | 默认 |
|---|---|---|
[app-url] | 您的应用程序的 URL( 位置参数) | 从软件包自动发现的。 json |
--client-id | 购买应用程序客户端ID | $SHOPIFY_API_KEY |
--client-secret | 模拟客户秘密 | "mock-secret-12345" |
--shop | 雾店域名 | "test-shop.myshopify.com" |
--port | 移动管理员端口 | 3080 |
--config | 配置文件路径 | "mock.config.js" |
--debug | 启用调试日志 | false |
环境变量
CLI 自动读取这些环境变量:
SHOPIFY_API_KEY=your-client-id # Used for --client-id
NODE_ENV=development # Enables mock token support
配置文件
生成配置文件 npx @getverdict/mock-bridge init数字 :
// mock.config.js
module.exports = {
appUrl: "http://localhost:3000/shopify", // Include path in URL
clientId: process.env.SHOPIFY_API_KEY,
clientSecret: "mock-secret-12345",
port: 3080,
shop: "test-shop.myshopify.com",
debug: true,
scopes: ["read_products", "write_products", "read_orders", "write_orders"],
};
* 如何运作
结构概览
┌─────────────────────────────────────┐
│ Mock Shopify Admin (Port 3080) │
│ ┌─────────────────────────────┐ │
│ │ Shopify Admin UI │ │
│ │ (Navigation, etc.) │ │
│ └─────────────────────────────┘ │
│ ┌─────────────────────────────┐ │
│ │ Your App (iframe) │ │ ← Embedded like real Shopify
│ │ - Mock App Bridge loaded │ │
│ │ - Gets mock session tokens │ │
│ │ - Makes API calls to your │ │
│ │ backend │ │
│ └─────────────────────────────┘ │
└─────────────────────────────────────┘
↕ PostMessage API
┌─────────────────────────────────────┐
│ Your Backend │
│ - Validates mock tokens │ ← Same backend, enhanced auth
│ - Skips Shopify API calls │
│ - Uses real database │
│ - Returns mock/real data │
└─────────────────────────────────────┘
模拟对真实流
雾环境(试验):
- Mock 管理员在 Iframe 为您的应用程序服务
- Moc App Bridge 提供会话符号
- 您的前端让 API 呼叫您的后端
- 后端检测模拟符并跳过 Shopify APIs
- 直接返回模拟数据或使用数据库
实际环境(生产):
- Real Shopify 管理员在 Iframe 为您的应用程序服务
- Real App 桥提供了会话符号
- 您的前端让 API 呼叫您的后端
- 后端检测真实的令牌并呼叫 Shopify API
- 从 Shostify 返回真实数据
QQ 配置选项
模拟服务器配置
const server = new MockShopifyAdminServer({
// Required
appUrl: "http://localhost:3000/shopify", // Your app's URL (with path)
clientId: "your-shopify-client-id", // Your Shopify app's client ID
clientSecret: "mock-secret-12345", // Mock secret (dev only)
// Optional
port: 3080, // Mock admin port
shop: "test-shop.myshopify.com", // Mock shop domain
apiVersion: "2024-01", // Shopify API version
scopes: [
// Your app's scopes
"read_products",
"write_products",
"read_orders",
"write_orders",
],
debug: true, // Enable debug logging
// Admin API handling (see below)
adminApi: "mock",
});
管理 API 配置
怎样控制 fetch('/admin/api/...') 处理请求:
// mock.config.js
// Option 1: Mock data (default) - returns fake data, works offline
module.exports = {
adminApi: "mock",
};
// Option 2: Proxy through your app - for real data via your backend
module.exports = {
adminApi: {
proxy: "http://localhost:3000/api/shopify-proxy",
},
};
// Option 3: Direct to Shopify - requires access token from installed shop
module.exports = {
adminApi: {
accessToken: process.env.SHOPIFY_ACCESS_TOKEN,
},
};
何时使用每个模式 :
| 模式 | 使用大小写 |
|---|---|
'mock' | 离线测试,CI/CD,不需要购买证书 |
{ proxy: '...' } | 通过您的应用程序后端代理进行真实的数据测试 |
{ accessToken: '...' } | 直接商店化API访问(需要安装商店) |
代理端点示例 (如果使用代理模式):
// pages/api/shopify-proxy.ts (Next.js example)
export default async function handler(req, res) {
const { url, method, body } = req.body;
const shop = await getShopFromSession(req);
const response = await fetch(`https://${shop.domain}${url}`, {
method,
headers: {
"X-Shopify-Access-Token": shop.accessToken,
"Content-Type": "application/json",
},
body: body ? JSON.stringify(body) : undefined,
});
res.json(await response.json());
}
认证选项
const authData = await validateSessionToken(token, {
shopifySecret: process.env.SHOPIFY_API_PRIVATE_KEY!, // Required
mockSecret: "custom-mock-secret", // Optional
developmentOnly: true, // Only try mock in dev
});
模拟用户选项
const mockUser = createMockUser({
shopName: "test-shop.myshopify.com",
userId: "123456789", // Custom user ID
email: "[email protected]", // Custom email
firstName: "Test", // Custom first name
lastName: "User", // Custom last name
permissions: ["read_products"], // Custom permissions
additionalProps: {
// Any additional props
posBillingTermsAcceptedAt: new Date(),
customField: "value",
},
});
使用自动化工具进行测试
剧作家示例
// playwright.config.ts
import { defineConfig } from "@playwright/test";
import { MockShopifyAdminServer } from "@getverdict/mock-bridge";
let mockServer: MockShopifyAdminServer;
export default defineConfig({
globalSetup: async () => {
mockServer = new MockShopifyAdminServer({
appUrl: "http://localhost:3000",
clientId: "test-client-id",
clientSecret: "mock-secret-12345",
port: 3080,
});
await mockServer.start();
},
globalTeardown: async () => {
await mockServer?.stop();
},
use: {
baseURL: "http://localhost:3080",
},
});
// tests/app.spec.ts
import { test, expect } from "@playwright/test";
test("should load app in mock Shopify admin", async ({ page }) => {
await page.goto("/");
// Wait for app to load in iframe
const appFrame = page.frameLocator("#app-iframe");
// Test your app functionality
await expect(appFrame.locator("h1")).toContainText("Your App Title");
// Test App Bridge actions
await appFrame.locator('button:has-text("Show Toast")').click();
await expect(page.locator(".toast")).toContainText("Success!");
// Test API calls
await appFrame.locator('button:has-text("Load Products")').click();
await expect(appFrame.locator(".product-list")).toBeVisible();
});
test("should handle authentication", async ({ page }) => {
await page.goto("/");
const appFrame = page.frameLocator("#app-iframe");
// Your app should be authenticated automatically
await expect(appFrame.locator(".user-info")).toContainText("Mock User");
await expect(appFrame.locator(".shop-info")).toContainText(
"test-shop.myshopify.com"
);
});
Jest 集成测试
// tests/api.test.ts
import { MockShopifyAdminServer } from "@getverdict/mock-bridge";
import {
createMockUser,
validateSessionToken,
} from "@verdict/shopify-app-bridge-mock/auth";
describe("API with Mock Tokens", () => {
let mockServer: MockShopifyAdminServer;
beforeAll(async () => {
mockServer = new MockShopifyAdminServer({
appUrl: "http://localhost:3000",
clientId: "test-client",
clientSecret: "mock-secret-12345",
});
await mockServer.start();
});
afterAll(async () => {
await mockServer.stop();
});
it("should authenticate with mock token", async () => {
// Generate mock token
const token = mockServer.tokenGenerator.generateSessionToken({
shop: "test-shop.myshopify.com",
clientId: "test-client",
clientSecret: "mock-secret-12345",
});
// Test authentication
const authData = await validateSessionToken(token, {
shopifySecret: "real-secret",
mockSecret: "mock-secret-12345",
});
expect(authData?.isMock).toBe(true);
expect(authData?.shopName).toBe("test-shop.myshopify.com");
});
it("should create mock users", async () => {
const mockUser = createMockUser({
shopName: "test-shop.myshopify.com",
permissions: ["read_products"],
});
expect(mockUser.email).toBe("[email protected]");
expect(mockUser.permissions).toContain("read_products");
});
});
安全考虑
仅限开发
模拟符号只用于开发和测试:
// ✅ Good: Mock tokens only in development
const authData = await validateSessionToken(token, {
shopifySecret: process.env.SHOPIFY_API_PRIVATE_KEY!,
developmentOnly: true, // Default: true
});
// ❌ Bad: Never allow mock tokens in production
const authData = await validateSessionToken(token, {
shopifySecret: process.env.SHOPIFY_API_PRIVATE_KEY!,
developmentOnly: false, // Don't do this!
});
环境变量
在制作时不要有嘲弄性的秘密:
# .env.local (development only)
SHOPIFY_API_PRIVATE_KEY=your-real-shopify-secret
MOCK_SECRET=mock-secret-12345
# .env.production (no mock secrets)
SHOPIFY_API_PRIVATE_KEY=your-real-shopify-secret
# No MOCK_SECRET in production!
数据库要求
模拟符号仍然需要您数据库中的有效商店 :
// Always verify shop exists, even for mock tokens
const authData = await validateSessionToken(token, options);
if (authData) {
const shop = await getShopByName(authData.shopName);
if (!shop) {
// Reject both mock and real tokens if shop doesn't exist
throw new Error("Shop not found");
}
}
* 解决问题
共同问题
不装入模拟管理员 :
- 检查 CSP 头部允许 iframe 嵌入
- 校验您的应用程序 URL 在模拟配置中正确
- 确保您的应用程序接受
embedded=1参数
模拟符号不起作用 :
- 校验
NODE_ENV=development - 检查前端和后端之间的模拟秘密匹配
- 确保数据库中存在商店
真正的令牌已损坏 :
- 校验
SHOPIFY_API_PRIVATE_KEY设置正确 - 请检查date=中的日期值 (帮助)
validateSessionToken - 确保保存您现有的 Shopify 认证流
调试模式
启用调试日志以排除出错 :
// Mock server with debug
const server = new MockShopifyAdminServer({
// ... config
debug: true,
});
// Frontend with debug
setupAppBridge({
debug: true,
onMockDetected: (url) => console.log("Mock detected:", url),
onShopifyDetected: () => console.log("Real Shopify detected"),
});
环境检查
校验您的环境设置 :
// Add to your app startup
console.log("Environment:", process.env.NODE_ENV);
console.log("Has Shopify Secret:", !!process.env.SHOPIFY_API_PRIVATE_KEY);
console.log("Mock tokens enabled:", process.env.NODE_ENV === "development");
API 参考
认证函数
validateSessionToken(token, options)
真实和模拟符号的通用验证器.
参数:
token: string- JWT会话符号options.shopifySecret: string- 真正的商店客户秘密options.mockSecret?: string- 雾密(默认:"雾密-12345")options.developmentOnly?: boolean- 只尝试开发中的模拟符号( 默认: 真实)
回返情况: AuthResult | false
isMockToken(token, mockSecret?)
快速检查是否是模拟符号 .
回返情况: boolean
createMockUser(options?)
生成模拟用户对象进行测试.
回返情况: MockCurrentUser
withMockTokenSupport(authFunction, shopifySecret, options?)
将模拟支持添加到现有认证函数中 .
服务器类
MockShopifyAdminServer
主模拟服务器类.
方法:
start()- 启动模拟服务器stop()- 停止模拟服务器getConfig()- 获得服务器配置
客户公用事业
setupAppBridge(options?)
自动检测模拟环境并装入适当的App Bridge.
回返情况: Promise<void>
关于完整的API文档,参见: 后端整合指南。 。 。 .
捐款
欢迎捐款! 请随意提交问题、特征请求或拉动请求.
开发设置
git clone <repository>
cd packages/shopify-app-bridge-mock
pnpm install
pnpm build
pnpm test
许可证
麻省理工学院许可证 - 详情见LICENSE文件.
承认
- 为 Shopify 开发者社区所建
- 受到需要更好的测试工具的启发
- 感谢所有捐助者和用户
与 QQ 一起制作, 供希望测试无痛的 Shopify 开发者使用