clerk-ci-integration

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Clerk CI Integration

Clerk CI集成

Overview

概述

Set up CI/CD pipelines with Clerk authentication testing.

设置包含Clerk身份验证测试的CI/CD流水线。

Prerequisites

前提条件

GitHub repository with Actions enabled
Clerk test API keys
npm/pnpm project configured

已启用Actions的GitHub仓库
Clerk测试API密钥
已配置的npm/pnpm项目

Instructions

操作步骤

Step 1: GitHub Actions Workflow

步骤1：GitHub Actions工作流

yaml

undefined

yaml

undefined

.github/workflows/test.yml

on: push: branches: [main] pull_request: branches: [main]

env: NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY: ${{ secrets.CLERK_PUBLISHABLE_KEY_TEST }} CLERK_SECRET_KEY: ${{ secrets.CLERK_SECRET_KEY_TEST }}

jobs: test: runs-on: ubuntu-latest

steps:
  - uses: actions/checkout@v4

  - name: Setup Node.js
    uses: actions/setup-node@v4
    with:
      node-version: '20'
      cache: 'npm'

  - name: Install dependencies
    run: npm ci

  - name: Type check
    run: npm run typecheck

  - name: Run unit tests
    run: npm test

  - name: Run integration tests
    run: npm run test:integration
    env:
      CLERK_SECRET_KEY: ${{ secrets.CLERK_SECRET_KEY_TEST }}

  - name: Build
    run: npm run build

undefined

on: push: branches: [main] pull_request: branches: [main]

env: NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY: ${{ secrets.CLERK_PUBLISHABLE_KEY_TEST }} CLERK_SECRET_KEY: ${{ secrets.CLERK_SECRET_KEY_TEST }}

jobs: test: runs-on: ubuntu-latest

steps:
  - uses: actions/checkout@v4

  - name: Setup Node.js
    uses: actions/setup-node@v4
    with:
      node-version: '20'
      cache: 'npm'

  - name: Install dependencies
    run: npm ci

  - name: Type check
    run: npm run typecheck

  - name: Run unit tests
    run: npm test

  - name: Run integration tests
    run: npm run test:integration
    env:
      CLERK_SECRET_KEY: ${{ secrets.CLERK_SECRET_KEY_TEST }}

  - name: Build
    run: npm run build

undefined

Step 2: E2E Testing with Playwright

步骤2：使用Playwright进行E2E测试

yaml

undefined

yaml

undefined

.github/workflows/e2e.yml

on: push: branches: [main] pull_request: branches: [main]

jobs: e2e: runs-on: ubuntu-latest

steps:
  - uses: actions/checkout@v4

  - name: Setup Node.js
    uses: actions/setup-node@v4
    with:
      node-version: '20'
      cache: 'npm'

  - name: Install dependencies
    run: npm ci

  - name: Install Playwright
    run: npx playwright install --with-deps

  - name: Build application
    run: npm run build
    env:
      NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY: ${{ secrets.CLERK_PUBLISHABLE_KEY_TEST }}

  - name: Run E2E tests
    run: npx playwright test
    env:
      NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY: ${{ secrets.CLERK_PUBLISHABLE_KEY_TEST }}
      CLERK_SECRET_KEY: ${{ secrets.CLERK_SECRET_KEY_TEST }}
      CLERK_TEST_USER_EMAIL: ${{ secrets.CLERK_TEST_USER_EMAIL }}
      CLERK_TEST_USER_PASSWORD: ${{ secrets.CLERK_TEST_USER_PASSWORD }}

  - name: Upload test results
    uses: actions/upload-artifact@v4
    if: always()
    with:
      name: playwright-report
      path: playwright-report/

undefined

on: push: branches: [main] pull_request: branches: [main]

jobs: e2e: runs-on: ubuntu-latest

steps:
  - uses: actions/checkout@v4

  - name: Setup Node.js
    uses: actions/setup-node@v4
    with:
      node-version: '20'
      cache: 'npm'

  - name: Install dependencies
    run: npm ci

  - name: Install Playwright
    run: npx playwright install --with-deps

  - name: Build application
    run: npm run build
    env:
      NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY: ${{ secrets.CLERK_PUBLISHABLE_KEY_TEST }}

  - name: Run E2E tests
    run: npx playwright test
    env:
      NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY: ${{ secrets.CLERK_PUBLISHABLE_KEY_TEST }}
      CLERK_SECRET_KEY: ${{ secrets.CLERK_SECRET_KEY_TEST }}
      CLERK_TEST_USER_EMAIL: ${{ secrets.CLERK_TEST_USER_EMAIL }}
      CLERK_TEST_USER_PASSWORD: ${{ secrets.CLERK_TEST_USER_PASSWORD }}

  - name: Upload test results
    uses: actions/upload-artifact@v4
    if: always()
    with:
      name: playwright-report
      path: playwright-report/

undefined

Step 3: Test User Setup

步骤3：测试用户设置

typescript

// scripts/setup-test-user.ts
import { clerkClient } from '@clerk/nextjs/server'

async function setupTestUser() {
  const client = await clerkClient()

  // Check if test user exists
  const { data: users } = await client.users.getUserList({
    emailAddress: ['test@example.com']
  })

  if (users.length === 0) {
    // Create test user
    const user = await client.users.createUser({
      emailAddress: ['test@example.com'],
      password: process.env.CLERK_TEST_USER_PASSWORD,
      firstName: 'Test',
      lastName: 'User'
    })
    console.log('Created test user:', user.id)
  } else {
    console.log('Test user already exists:', users[0].id)
  }
}

setupTestUser()

typescript

// scripts/setup-test-user.ts
import { clerkClient } from '@clerk/nextjs/server'

async function setupTestUser() {
  const client = await clerkClient()

  // Check if test user exists
  const { data: users } = await client.users.getUserList({
    emailAddress: ['test@example.com']
  })

  if (users.length === 0) {
    // Create test user
    const user = await client.users.createUser({
      emailAddress: ['test@example.com'],
      password: process.env.CLERK_TEST_USER_PASSWORD,
      firstName: 'Test',
      lastName: 'User'
    })
    console.log('Created test user:', user.id)
  } else {
    console.log('Test user already exists:', users[0].id)
  }
}

setupTestUser()

Step 4: Playwright Test Configuration

步骤4：Playwright测试配置

typescript

// playwright.config.ts
import { defineConfig, devices } from '@playwright/test'

export default defineConfig({
  testDir: './e2e',
  fullyParallel: true,
  forbidOnly: !!process.env.CI,
  retries: process.env.CI ? 2 : 0,
  workers: process.env.CI ? 1 : undefined,
  reporter: 'html',

  use: {
    baseURL: 'http://localhost:3000',
    trace: 'on-first-retry',
  },

  projects: [
    {
      name: 'chromium',
      use: { ...devices['Desktop Chrome'] },
    },
  ],

  webServer: {
    command: 'npm run start',
    url: 'http://localhost:3000',
    reuseExistingServer: !process.env.CI,
  },
})

typescript

// playwright.config.ts
import { defineConfig, devices } from '@playwright/test'

export default defineConfig({
  testDir: './e2e',
  fullyParallel: true,
  forbidOnly: !!process.env.CI,
  retries: process.env.CI ? 2 : 0,
  workers: process.env.CI ? 1 : undefined,
  reporter: 'html',

  use: {
    baseURL: 'http://localhost:3000',
    trace: 'on-first-retry',
  },

  projects: [
    {
      name: 'chromium',
      use: { ...devices['Desktop Chrome'] },
    },
  ],

  webServer: {
    command: 'npm run start',
    url: 'http://localhost:3000',
    reuseExistingServer: !process.env.CI,
  },
})

Step 5: Authentication Test Helpers

步骤5：身份验证测试辅助工具

typescript

// e2e/helpers/auth.ts
import { Page } from '@playwright/test'

export async function signIn(page: Page) {
  await page.goto('/sign-in')

  await page.fill('input[name="identifier"]', process.env.CLERK_TEST_USER_EMAIL!)
  await page.click('button:has-text("Continue")')

  await page.fill('input[name="password"]', process.env.CLERK_TEST_USER_PASSWORD!)
  await page.click('button:has-text("Continue")')

  // Wait for redirect to dashboard
  await page.waitForURL('/dashboard')
}

export async function signOut(page: Page) {
  await page.click('[data-clerk-user-button]')
  await page.click('button:has-text("Sign out")')
  await page.waitForURL('/')
}

typescript

// e2e/helpers/auth.ts
import { Page } from '@playwright/test'

export async function signIn(page: Page) {
  await page.goto('/sign-in')

  await page.fill('input[name="identifier"]', process.env.CLERK_TEST_USER_EMAIL!)
  await page.click('button:has-text("Continue")')

  await page.fill('input[name="password"]', process.env.CLERK_TEST_USER_PASSWORD!)
  await page.click('button:has-text("Continue")')

  // Wait for redirect to dashboard
  await page.waitForURL('/dashboard')
}

export async function signOut(page: Page) {
  await page.click('[data-clerk-user-button]')
  await page.click('button:has-text("Sign out")')
  await page.waitForURL('/')
}

Step 6: Sample E2E Tests

步骤6：示例E2E测试

typescript

// e2e/auth.spec.ts
import { test, expect } from '@playwright/test'
import { signIn, signOut } from './helpers/auth'

test.describe('Authentication', () => {
  test('user can sign in and access dashboard', async ({ page }) => {
    await signIn(page)
    await expect(page).toHaveURL('/dashboard')
    await expect(page.locator('h1')).toContainText('Dashboard')
  })

  test('user can sign out', async ({ page }) => {
    await signIn(page)
    await signOut(page)
    await expect(page).toHaveURL('/')
  })

  test('unauthenticated user is redirected', async ({ page }) => {
    await page.goto('/dashboard')
    await expect(page).toHaveURL(/\/sign-in/)
  })
})

typescript

// e2e/auth.spec.ts
import { test, expect } from '@playwright/test'
import { signIn, signOut } from './helpers/auth'

test.describe('Authentication', () => {
  test('user can sign in and access dashboard', async ({ page }) => {
    await signIn(page)
    await expect(page).toHaveURL('/dashboard')
    await expect(page.locator('h1')).toContainText('Dashboard')
  })

  test('user can sign out', async ({ page }) => {
    await signIn(page)
    await signOut(page)
    await expect(page).toHaveURL('/')
  })

  test('unauthenticated user is redirected', async ({ page }) => {
    await page.goto('/dashboard')
    await expect(page).toHaveURL(/\/sign-in/)
  })
})

Output

输出结果

GitHub Actions workflows configured
E2E tests with Playwright
Test user management
CI/CD pipeline ready

已配置GitHub Actions工作流
基于Playwright的E2E测试
测试用户管理
就绪的CI/CD流水线

Secret Configuration

密钥配置

Required GitHub Secrets:

```
CLERK_PUBLISHABLE_KEY_TEST
```
- Test publishable key
```
CLERK_SECRET_KEY_TEST
```
- Test secret key
```
CLERK_TEST_USER_EMAIL
```
- Test user email
```
CLERK_TEST_USER_PASSWORD
```
- Test user password

所需GitHub Secrets：

```
CLERK_PUBLISHABLE_KEY_TEST
```
- 测试用可发布密钥
```
CLERK_SECRET_KEY_TEST
```
- 测试用密钥
```
CLERK_TEST_USER_EMAIL
```
- 测试用户邮箱
```
CLERK_TEST_USER_PASSWORD
```
- 测试用户密码

Error Handling

错误处理

Error	Cause	Solution
Secret not found	Missing GitHub secret	Add secret in repo settings
Test user not found	User not created	Run setup script first
Timeout on sign-in	Slow response	Increase timeout, check network
Build fails	Missing env vars	Check all NEXT_PUBLIC vars set

错误	原因	解决方案
未找到密钥	缺少GitHub密钥	在仓库设置中添加密钥
未找到测试用户	用户未创建	先运行设置脚本
登录超时	响应缓慢	增加超时时间，检查网络
构建失败	缺少环境变量	检查所有NEXT_PUBLIC变量是否已设置

Resources

参考资源

Next Steps

下一步操作

Proceed to

clerk-deploy-integration

for deployment platform setup.

继续执行

clerk-deploy-integration

以完成部署平台设置。