shopify-testing

用途

本技能是一份 Shopify 应用测试指南，目标是帮助开发者确保应用能够正确处理 Shopify 的认证机制与 API 特性。可靠的测试对于验证应用在认证、API 调用、Webhook 等环节的行为至关重要。

主要能力

该指南覆盖以下测试类型：

单元与集成测试（Vitest + Remix）：在 Remix 环境中使用 Vitest 运行单元和集成测试。
模拟 Shopify 上下文：通过 mock shopify.server.ts 中的 authenticate 对象，在不调用真实 Shopify API 的情况下测试 loader 和 action。
测试 Loaders 与 Actions：使用 Remix 的 createRemixStub 或直接调用 loader/action 来测试后端逻辑。
端到端（E2E）测试（Playwright）：处理 OAuth 流程或使用会话令牌绕过认证。
测试 Webhooks：在本地触发或通过单元测试验证 Webhook。

使用方式

1. 单元与集成测试环境搭建

安装依赖：

npm install -D vitest @testing-library/react @testing-library/jest-dom jsdom

2. 模拟 shopify.server.ts

创建 authenticate 对象的 mock 是测试 loader 和 action 的关键，可避免调用真实 Shopify API。

// test/mocks/shopify.ts
import { vi } from 'vitest';

export const mockShopify = {
  authenticate: {
    admin: vi.fn(),
    public: vi.fn(),
    webhook: vi.fn(),
  },
};

// Usage in test file:
vi.mock('../app/shopify.server', () => mockShopify);

test('loader returns data for authenticated shop', async () => {
    mockShopify.authenticate.admin.mockResolvedValue({
        currentShop: 'test-shop.myshopify.com',
        session: { shop: 'test-shop.myshopify.com', accessToken: 'fake_token' },
        admin: {
             graphql: vi.fn().mockResolvedValue({ /* mock response */ })
        }
    });

    const response = await loader({ request: new Request('http://localhost/') });
    // Assertions...
});

3. 测试 Loaders 与 Actions

直接调用函数（推荐用于逻辑测试）：可以导入 loader 或 action，并用 mock Request 直接调用。

import { loader } from '../app/routes/app.dashboard';

test('dashboard loader returns stats', async () => {
   // Setup mocks...
   const response = await loader({ 
       request: new Request('http://localhost/app/dashboard'), 
       params: {} 
   });
   const data = await response.json();
   expect(data.stats).toBeDefined();
});

4. 端到端（E2E）测试（Playwright）

对于 E2E 测试，需要处理 OAuth 流程或使用会话令牌绕过它。绕过认证（会话令牌）是测试嵌入式应用最稳定的方式：生成有效的会话令牌（或模拟验证），从而无需自动化登录界面交互（登录界面常触发验证码）。

基础 Playwright 测试示例：

import { test, expect } from '@playwright/test';

test('load dashboard', async ({ page }) => {
  await page.goto('http://localhost:3000/app');
  // Expect to see the Polaris Page title
  await expect(page.locator('.Polaris-Page-Header__Title')).toHaveText('Dashboard');
});

5. 测试 Webhooks

在本地测试 Webhook 的方式：

通过 Shopify CLI 触发：shopify app webhook trigger --topic ORDERS_CREATE
单元测试：导入 webhook action，并传入带有正确 HMAC 头的 mock Request。

import { action } from '../app/routes/webhooks';
import crypto from 'crypto';

test('webhook verifies hmac', async () => {
    const payload = JSON.stringify({ id: 123 });
    const hmac = crypto.createHmac('sha256', 'FULL_SECRET').update(payload).digest('base64');
    
    const request = new Request('http://localhost/webhooks', {
        method: 'POST',
        body: payload,
        headers: { 'X-Shopify-Hmac-Sha256': hmac }
    });

    // Mock authenticate.webhook to succeed
    // ...
    
    const response = await action({ request });
    expect(response.status).toBe(200);
});

适用场景

开发 Shopify 应用时，需要为 loader、action 等后端逻辑编写单元或集成测试。
需要在测试中模拟 Shopify 认证上下文，避免调用真实 API。
需要对嵌入式 Shopify 应用进行端到端测试，并希望绕过 OAuth 登录流程。
需要在本地验证 Webhook 的 HMAC 签名与处理逻辑。

限制

资料中未提供关于该技能的具体版本要求、兼容性范围、性能指标或收费信息，这些内容暂未提供。