Playwright + TypeScript 搞定 Salesforce API 测试

REST、OAuth、Bulk API 与集成测试

作者：Himanshu Agarwal

大多数团队把 Salesforce API 测试当作事后工作。他们写几个愉快的路径测试——POST /sobjects/Account 检查，然后把它们挂到一个夜间任务里，就宣称集成"已覆盖"。然后 Winter 版本发布，Named Credential 轮换，一个 Bulk 任务因为 CSV 列格式错误悄无声息地丢弃了一万条记录，而 on-call 工程师花了一个周末来重建流水线实际做了什么。

如果你有五到十五年构建分布式系统的经验，你已经知道这为什么发生。Salesforce 不是你拿来测试的 REST API。它是一个多租户平台，有着 governor limits、异步任务、专有的查询语言、覆盖六种 OAuth 流的认证层面，以及一个其他企业系统——SAP、Oracle、MuleSoft、Kafka、支付网关——不断写入的数据模型。要做好测试，意味着要测试这些系统之间的接缝，而不是仅仅测试端点。

本文讲的是用 Playwright 和 TypeScript 构建生产级别的 Salesforce API 测试框架。Playwright 的 APIRequestContext 悄然已成为测试工程领域最好的 HTTP 客户端之一：它速度快，与你的 UI 测试运行在同一运行时，有一流的 fixtures、tracing 和 reporting，而且它不会强迫你为了发一个认证请求而引入一个单独的工具。我们将用它作为请求层，在此之上构建企业需要的一切：token 生命周期管理、重试与限流处理、correlation ID、schema 验证、Bulk API 编排、安全断言，以及 CI/CD 接入。

这是 2026 版，具体细节很重要。在当前的 Salesforce 发布节奏中，Winter '26 作为 API 版本 65.0 发布，Spring '26 作为版本 66.0，平台继续保持每年三个版本的节奏，并且至少支持三年的版本窗口。Playwright 的 APIRequestContext 现在支持 failOnStatusCode 和改进的 tracing 等选项，这些改变了你构建框架的方式。OWASP 的 API Security Top 10 仍然停留在 2023 版，围绕授权和业务流滥用重新组织了风险格局。我们将基于这些现实来构建，而不是基于 2021 年的心智模型。

这里一切都是面向实现的。你会看到文件夹结构、fixtures、重试逻辑、JWT 签名、Bulk 摄入编排，以及你可以直接适配的 CI 流水线。目标是构建一个你真正会拿来在生产 org 上运行的框架。

HimanshuAI 八月促销 — 限时 95% 折扣

HimanshuAI 八月促销现已开始。

限时优惠，获取我全部精选 AI 工程数字攻略的 95% 折扣。

• GenAI 工程知识库 — 16 本书 https://himanshuai.gumroad.com/l/GenAIEngineeringVault16Books

• 全套 — LLM 与生成式 AI 测试专业版 https://himanshuai.gumroad.com/l/THEBUNDLE-LLMGenerativeAITestingPro

• AI 编码智能体精通 — 第一卷 https://himanshuai.gumroad.com/l/Bundle-AICodingAgentsMastery-Volume1

• Ollama 与本地 LLM — 完整四本书系列 https://himanshuai.gumroad.com/l/Ollama-Local-LLMs-The-Complete4-Book-Series

• AWS 云测试师套装 https://himanshuai.gumroad.com/l/The-Complete-AWS-Cloud-Tester-3-Books-Bundle

• Salesforce 自动化测试精通系列 https://himanshuai.gumroad.com/l/SalesforceAutomationTestingMasterySeries

• AI Playwright + TypeScript 精通套装 https://himanshuai.gumroad.com/l/The-Complete-AI-Playwright-TypeScript-Mastery-Bundle

https://himanshuai.gumroad.com/

为什么企业级 Salesforce API 测试与众不同

通用的 REST API 返回可预测的状态码，对每个调用者行为一致。Salesforce 不是，这其中的差异正是企业级测试套件崩溃的地方。

第一个差异是 governor limits。Salesforce 强制执行按 org、滚动 24 小时的 API 请求配额，与版本和许可证数量绑定，还有并发长期请求限制，以及 Apex 内每事务限制。一个并行轰炸 org 的测试套件不只是有 flakiness 的风险——它可能耗尽 org 的每日配额，并让共享该 org 的真实集成宕机。你的框架必须成为一个好租户。

第二个是 Salesforce 的失败方式不符合你的预期。没有干净的、统一的 429 Too Many Requests。当你超过每日 API 请求限制时，经典响应是 HTTP 403，body 中有错误码 REQUEST_LIMIT_EXCEEDED。并发请求上限又以不同方式出现，而且只有一些较新的平台 surface 才会发出带 Retry-After 头部的真正 429。如果你的重试逻辑仅仅基于 429 状态，它将完全错过最常见的 Salesforce 限流情况。稳健的处理方式需要解析 Salesforce 错误码，而不仅仅是 HTTP 状态。

第三个是异步性。Bulk API 2.0、Metadata API、Platform Events 和 Change Data Capture 都是最终一致的。你提交一个 job，得到一个 accepted 响应，实际工作稍后发生。一个在提交后立即断言的测试测的是队列，而不是结果。真正的覆盖意味着轮询 job 状态、协调成功和失败记录集，并在事后验证数据完整性。

第四个是认证层面。一个典型的服务只有一种认证机制。一个严肃的 Salesforce 集成涉及多种：面向用户应用的 Authorization Code with PKCE、服务器到服务器自动化的 JWT Bearer、无头服务的 Client Credentials、长期会话的 refresh token，以及为 Apex callouts 抽象一切的 Named Credentials。每种都有不同的 token 生命周期，每种都以不同方式失败。

第五个是生态系统。没有人孤立地运行 Salesforce。Leads 从营销平台流入，订单同步到 SAP，entitlements 从计费系统到达，事件通过 Kafka 或 MuleSoft 流式传输。生产中最痛苦的 bug 不在 Salesforce 内部——而在 Salesforce 与其他一切之间的转换层。企业级测试必须对这些契约进行断言。

现代 Salesforce API 生态系统

在写任何测试之前，你需要一张有效的 API 心智地图，知道每个 API 做什么，因为选错 API 是 Salesforce 测试设计中最常见的架构错误。

REST API 是同步、记录级 CRUD 的主力。它通过 /services/data/vXX.0/sobjects/{Object} 暴露，通过 /query 暴露 SOQL 查询，通过 /search 暴露搜索。它是你默认会去使用的，也是大多数功能测试会用到的。

SOAP API 先于 REST 存在，至今仍被遗留中间件和使用 Enterprise 或 Partner WSDL 的工具大量使用。如果你正在测试一个构建在旧版 MuleSoft 或 Boomi 连接器上的集成，你可能正在断言 SOAP payload，无论你愿意与否。Playwright 可以发送原始 XML body，所以它能处理 SOAP，但预期会有冗长的 envelope。

Composite API 是效率之选。/composite 将最多 25 个子请求批处理成一次往返，并允许后面的子请求通过 referenceId 引用前面的子请求——这对于在单个调用中创建父记录和子记录来说非常宝贵。/composite/tree/{Object} 插入最多 200 条记录的嵌套记录树。sObject Collections 端点（/composite/sobjects）在一次请求中操作最多 200 条同类型记录。/composite/graph 处理具有事务边界的更复杂依赖图。

Bulk API 2.0 用于大容量场景。它是基于 CSV 的，完全异步：你创建一个 ingest job，上传数据，标记完成，然后轮询结果。它是处理任何超过几千条记录的正确工具，而且它有着与 REST 完全不同的失败语义。

Streaming API 覆盖事件驱动的 surface：PushTopics、通用事件、Platform Events 和 Change Data Capture，通过 CometD/长轮询投递。测试它意味着订阅、触发一个变更，然后断言事件到达——这是一种真正不同于请求/响应的模式。

Tooling API 用于开发和与 metadata 相关的操作：Apex 执行、代码覆盖率、符号表，以及在最近的版本中，统一测试发现和执行端点。测试基础设施工具经常依赖它。

Metadata API 部署和检索 org 配置。你很少通过它来断言业务逻辑，但部署验证测试和环境漂移检查在这里。

GraphQL API，可通过 /services/data/vXX.0/graphql 访问，让客户端在一次查询中精确请求跨相关对象所需的字段。它越来越多地被 Lightning 组件和移动客户端使用，值得拥有自己的契约测试，因为响应的形状是由客户端定义的。

选择正确的 API

一旦说明白，决策规则就很简单。REST 用于单记录和小批量同步操作。当需要将多个有依赖关系的 REST 调用合并为原子操作或节省往返时间时，使用 Composite。当记录数达到数千条或需要验证数据迁移时，使用 Bulk 2.0。当要测试的行为是事件传递时，使用 Streaming。当客户端需要控制响应形状且需要防止过度抓取或不足抓取时，使用 GraphQL。只有在所测试的集成本身使用 SOAP 时才使用 SOAP。选错方案不仅仅会让测试变慢——还会让测试撒谎，因为一个在 HTTP 层面"成功"的 Bulk 任务可能每一行都失败了。

企业级身份验证

大多数 Salesforce 测试框架在身份验证上要么保持简单而脆弱，要么变得健壮且可复用。区别在于是否将令牌获取作为一等公民、缓存化、可观测的子系统，而不是复制粘贴的帮助函数。

你实际要测试的授权流程

授权码（带 PKCE）是面向用户的流程。自动化测试套件很少为 API 测试驱动完整的浏览器重定向，但你确实要测试使用该流程的应用的令牌交换和刷新行为。RFC 6749 定义了该流程；PKCE（RFC 7636）现在即使对机密客户端也是必需的。

JWT Bearer 是针对 Salesforce 进行无头 CI 自动化运行的支柱。你在 Connected App 上注册一个数字证书，用匹配的私钥签署一个 JWT，然后交换它以获取访问令牌。没有用户交互，也没有刷新令牌——你只是在令牌过期时生成一个新的断言。这几乎是测试框架的正确选择。

客户端凭据是 Salesforce 用于无用户上下文集成的服务端到服务端流程。你在 Connected App 上启用它并指定一个 run-as 用户。它返回一个具有该用户权限的访问令牌，与 JWT 一样，不发放刷新令牌。

刷新令牌流程使完成了初始交互登录的应用保持长期会话存活。在测试中，你验证刷新能获取新的访问令牌，且旧令牌按策略被作废。

命名凭据是 Salesforce 端的抽象：它存储 Apex 或 Flow 发起的出站调用所需端点和身份验证信息，这样开发者无需处理原始令牌。你不会通过 Playwright 对它们进行身份验证，但当你测试 Apex 驱动的集成时，命名凭据是可能出现配置错误的地方，所以你的负面测试应该将其纳入考虑。

JWT Bearer 实战

JWT Bearer 流程值得从头到尾展示，因为它将是你的框架所依赖的核心。断言是一个已签名的 JWT，其声明标识 Connected App（iss）、要模拟的用户（sub）、登录受众（aud）和几分钟后的过期时间（exp）。它用与上传到 Connected App 的证书匹配的私钥进行 RS256 签名。

// src/auth/jwt-bearer.ts
import { createSign } from 'crypto';
import { readFileSync } from 'fs';

interface JwtBearerConfig {
  clientId: string;        // Connected App consumer key
  username: string;        // user to impersonate (sub)
  loginUrl: string;        // https://login.salesforce.com or My Domain / test.salesforce.com
  privateKeyPath: string;  // PEM private key matching the app certificate
}

function base64url(input: Buffer | string): string {
  return Buffer.from(input)
    .toString('base64')
    .replace(/=/g, '')
    .replace(/\+/g, '-')
    .replace(/\//g, '_');
}

export function buildSignedAssertion(cfg: JwtBearerConfig): string {
  const header = base64url(JSON.stringify({ alg: 'RS256', typ: 'JWT' }));
  const claims = base64url(
    JSON.stringify({
      iss: cfg.clientId,
      sub: cfg.username,
      aud: cfg.loginUrl,
      exp: Math.floor(Date.now() / 1000) + 180, // 3 minute window
    }),
  );

  const signingInput = `${header}.${claims}`;
  const privateKey = readFileSync(cfg.privateKeyPath, 'utf8');
  const signature = createSign('RSA-SHA256')
    .update(signingInput)
    .sign(privateKey);

  return `${signingInput}.${base64url(signature)}`;
}

令牌交换本身是一个单一的表单 POST。注意我们在 JWT Bearer 中从不传递客户端密钥——签名本身就是证明。

// src/auth/token-service.ts
import { APIRequestContext, request as playwrightRequest } from '@playwright/test';
import { buildSignedAssertion } from './jwt-bearer';

export interface SalesforceSession {
  accessToken: string;
  instanceUrl: string;
  issuedAt: number;
  expiresInMs: number;
}

const JWT_GRANT = 'urn:ietf:params:oauth:grant-type:jwt-bearer';

export class TokenService {
  private cached?: SalesforceSession;
  // 在真实过期前一点就刷新，避免测试中途出现 401。
  private readonly safetyWindowMs = 120_000;

  async getSession(): Promise<SalesforceSession> {
    if (this.cached && !this.isExpiring(this.cached)) {
      return this.cached;
    }
    this.cached = await this.mintSession();
    return this.cached;
  }

  private isExpiring(s: SalesforceSession): boolean {
    return Date.now() > s.issuedAt + s.expiresInMs - this.safetyWindowMs;
  }

  private async mintSession(): Promise<SalesforceSession> {
    const assertion = buildSignedAssertion({
      clientId: process.env.SF_CLIENT_ID!,
      username: process.env.SF_USERNAME!,
      loginUrl: process.env.SF_LOGIN_URL!,
      privateKeyPath: process.env.SF_JWT_KEY_PATH!,
    });

    const ctx: APIRequestContext = await playwrightRequest.newContext();
    const res = await ctx.post(`${process.env.SF_LOGIN_URL}/services/oauth2/token`, {
      form: { grant_type: JWT_GRANT, assertion },
    });

    if (!res.ok()) {
      const body = await res.text();
      await ctx.dispose();
      throw new Error(`JWT token exchange failed ${res.status()}: ${body}`);
    }

    const json = await res.json();
    await ctx.dispose();

    // Salesforce 访问令牌在此响应中不携带数字 TTL；
    // 将其视为会话生命周期，并保守地设定我们自己的缓存上限。
    return {
      accessToken: json.access_token,
      instanceUrl: json.instance_url,
      issuedAt: Date.now(),
      expiresInMs: 60 * 60 * 1000,
    };
  }

  invalidate(): void {
    this.cached = undefined;
  }
}

令牌生命周期、过期和密钥管理

两个失败模式主导着真实测试套件。第一个是中途 401：在长时间并行运行开始时获取的令牌在最后一个测试使用它之前就已过期。上面的安全窗口缓存处理了这个问题，接下来构建的请求层还会在遇到 401 时重新生成令牌并重试一次。第二个是泄露的密钥。永远不要提交私钥、消费密钥或用户名。在 CI 中，它们属于运行器的密钥库；在本地，它们属于未被跟踪的 .env 文件，或者更好的做法是从 vault 在运行时拉取。

vault 集成保持相同的接口，但从外部获取密钥，这意味着轮换永远不需要代码更改：

// src/auth/secret-provider.ts
export interface SecretProvider {
  get(key: string): Promise<string>;
}

// Vault 支持的 provider（HashiCorp Vault、AWS Secrets Manager、Azure Key Vault
// 都符合此形状）。每个进程获取一次，在进程内缓存，永远不记录值。
export class VaultSecretProvider implements SecretProvider {
  private cache = new Map<string, string>();
  constructor(private readonly fetcher: (k: string) => Promise<string>) {}

  async get(key: string): Promise<string> {
    if (!this.cache.has(key)) {
      this.cache.set(key, await this.fetcher(key));
    }
    return this.cache.get(key)!;
  }
}

真正重要的纪律：密钥在每个进程中读取一次，在内存中缓存，永远不写入日志、报告或追踪文件。Playwright 追踪会捕获请求体，所以在 Authorization header 和任何令牌到达磁盘之前，在你的日志层中清除它们。

Playwright API 测试架构

框架不是一堆测试文件。它是一组职责清晰的层次，这样面向业务的测试读起来像业务语言，底层细节则隐藏在它下面。

salesforce-api-tests/
  src/
    auth/
      jwt-bearer.ts
      token-service.ts
      secret-provider.ts
    core/
      sf-client.ts          # 基于 APIRequestContext 的请求层
      retry.ts              # 重试 + 退避策略
      correlation.ts        # 关联 ID 生成
      logger.ts             # 结构化、去密钥化的日志
      errors.ts             # 类型化的 Salesforce 错误解析
    domain/
      accounts.ts           # Account 特定的请求帮助函数
      leads.ts
      opportunities.ts
      bulk.ts               # Bulk API 2.0 编排
    schemas/
      account.schema.json
      lead.schema.json
    config/
      env.ts                # 类型化的环境变量加载器
  tests/
    rest/
    composite/
    bulk/
    contract/
    security/
    performance/
  fixtures/
    sf-fixtures.ts
  playwright.config.ts

配置与环境管理

环境漂移——测试在 QA 环境通过、在 staging 环境失败，原因是 URL、limit 或 feature flag 不同——是导致 Salesforce 测试套件"不稳定"的首要原因之一。通过类型化、显式的配置来消除它，当缺少某些内容时快速失败。

// src/config/env.ts
function required(name: string): string {
  const v = process.env[name];
  if (!v) throw new Error(`Missing required env var: ${name}`);
  return v;
}

export const env = {
  loginUrl: required('SF_LOGIN_URL'),
  apiVersion: process.env.SF_API_VERSION ?? 'v65.0',
  clientId: required('SF_CLIENT_ID'),
  username: required('SF_USERNAME'),
  jwtKeyPath: required('SF_JWT_KEY_PATH'),
  maxRetries: Number(process.env.SF_MAX_RETRIES ?? 3),
  requestTimeoutMs: Number(process.env.SF_TIMEOUT_MS ?? 30_000),
} as const;

export type Env = typeof env;

显式固定 API 版本，而不是总追逐最新版本。Salesforce 保证每个版本有多年的支持窗口，固定版本意味着发布升级不会在断言下悄然改变响应结构。你是有意识地升级版本、运行测试套件，然后才继续前进。

Fixtures 与依赖注入

Playwright fixtures 是测试工程师可用的最简洁的依赖注入机制。我们构建一个单一的身份验证后 Salesforce 客户端 fixture，每个测试可以通过名称请求它，Playwright 负责构造和清理。

// fixtures/sf-fixtures.ts
import { test as base } from '@playwright/test';
import { TokenService } from '../src/auth/token-service';
import { SalesforceClient } from '../src/core/sf-client';

type SfFixtures = {
  sf: SalesforceClient;
};

// Worker-scoped token service so we mint one session per worker, not per test.
const tokenService = new TokenService();

export const test = base.extend<SfFixtures>({
  sf: async ({ playwright }, use) => {
    const session = await tokenService.getSession();
    const client = await SalesforceClient.create(playwright, session, tokenService);
    await use(client);
    await client.dispose();
  },
});

export { expect } from '@playwright/test';

现在测试只需要请求 sf，就会收到一个完全已认证、支持重试、有日志记录的客户端。没有测试会接触 token。

企业级 API 框架设计

这是框架的核心：一个请求层，将 Playwright 原始的 APIRequestContext 转换为大型团队可以依赖的东西。它负责管理请求头、重试、限流感知、关联 ID 和结构化日志。

// src/core/sf-client.ts
import { APIRequestContext, APIResponse, Playwright } from '@playwright/test';
import { SalesforceSession, TokenService } from '../auth/token-service';
import { withRetry } from './retry';
import { newCorrelationId } from './correlation';
import { logger } from './logger';
import { parseSalesforceError } from './errors';
import { env } from '../config/env';

export interface SfRequestOptions {
  headers?: Record<string, string>;
  data?: unknown;
  params?: Record<string, string | number>;
}

export class SalesforceClient {
  private constructor(
    private ctx: APIRequestContext,
    private session: SalesforceSession,
    private tokens: TokenService,
  ) {}

static async create(
    pw: Playwright,
    session: SalesforceSession,
    tokens: TokenService,
  ): Promise<SalesforceClient> {
    const ctx = await pw.request.newContext({
      baseURL: session.instanceUrl,
      timeout: env.requestTimeoutMs,
      // failOnStatusCode stays false: we want to inspect and classify errors,
      // not throw blindly on the first non-2xx.
    });
    return new SalesforceClient(ctx, session, tokens);
  }

private path(resource: string): string {
    return `/services/data/${env.apiVersion}/${resource.replace(/^\//, '')}`;
  }

private baseHeaders(correlationId: string): Record<string, string> {
    return {
      Authorization: `Bearer ${this.session.accessToken}`,
      'Content-Type': 'application/json',
      'X-Correlation-Id': correlationId,
    };
  }

async send(
    method: 'GET' | 'POST' | 'PATCH' | 'DELETE',
    resource: string,
    opts: SfRequestOptions = {},
  ): Promise<APIResponse> {
    const correlationId = newCorrelationId();
    const url = this.path(resource);

return withRetry(
      async () => {
        const res = await this.ctx.fetch(url, {
          method,
          headers: { ...this.baseHeaders(correlationId), ...opts.headers },
          data: opts.data as any,
          params: opts.params,
        });

logger.info('sf.request', {
          correlationId,
          method,
          url,
          status: res.status(),
        });

// Re-mint on auth failure, then let retry re-run once with a fresh token.
        if (res.status() === 401) {
          this.tokens.invalidate();
          this.session = await this.tokens.getSession();
          throw new RetryableError('token_expired', correlationId);
        }

const err = await parseSalesforceError(res);
        if (err?.retryable) {
          throw new RetryableError(err.code, correlationId);
        }
        return res;
      },
      { correlationId },
    );
  }

async dispose(): Promise<void> {
    await this.ctx.dispose();
  }
}

export class RetryableError extends Error {
  constructor(public code: string, public correlationId: string) {
    super(`retryable:${code}`);
  }
}

框架中 Salesforce 特定逻辑最有价值的部分是对错误进行正确分类。Salesforce 将真正的原因编码在响应体中，而不仅仅是状态行。

// src/core/errors.ts
import { APIResponse } from '@playwright/test';

const RETRYABLE_SF_CODES = new Set([
  'REQUEST_LIMIT_EXCEEDED',      // daily API allocation (HTTP 403)
  'SERVER_UNAVAILABLE',
  'UNABLE_TO_LOCK_ROW',          // row-lock contention, transient
]);

export int