如何使用高级TypeScript模式构建可扩展的QA框架
TypeScript自动化QA（7部分系列）
🗺️ TypeScript第一步：自动化QA实用路线图
🗂️ 如何在TypeScript中使用数组和对象构建强大的QA自动化脚本
🔀 如何掌握TypeScript基础逻辑以构建更智能的自动化QA
🏷️ TypeScript自定义类型QA自动化实用指南
🏛️ 停止编写脆弱的测试：可扩展TypeScript POM蓝图
⚡️ 停止编写不稳定的测试：Playwright异步基础指南
🛡️ 如何使用高级TypeScript模式构建可扩展的QA框架
🤖 在我们的上一篇文章中，我们掌握了异步性，为我们的测试框架奠定了坚实的基础。但坚实的基础只是开始。要构建真正可扩展和可维护的自动化套件，我们需要一个强大的架构框架。这个框架就是高级的、表达性强的类型系统。
本文适合高级用户。我们将超越基础类型，向你展示如何利用TypeScript的高级模式来消除整类bug，甚至在你运行单个测试之前。
你将学习构建世界级QA框架的五个基本模式：
枚举（Enums）：管理固定常量集合并防止拼写错误
泛型（Generics）：编写高度可重用、类型安全的代码，如API客户端
Zod & z.infer：在运行时验证API响应并消除手动类型定义
typeof：直接从运行时对象创建类型
工具类型（Utility Types）：创建现有类型的灵活变体，无需重复代码
掌握这些概念将把你的框架从简单的测试集合转变为可扩展、自文档化和有弹性的资产。
前置要求：
TypeScript基础：
基本TypeScript类型（string、number、boolean）
使用数组和对象构建数据
使用函数编写可重用代码
使用循环自动化操作（for、while）
使用条件语句做出决策（if/else）
联合类型和字面量类型
类型别名和接口
Playwright项目：你应该对如何编写和运行测试有基本了解
你理解页面对象模型（类）的目的
你理解并正确使用async/await、Promise.all和try/catch
🤔 问题："简单"框架的隐藏成本
当框架很小时，保持清洁很容易。但随着它的增长，"简单"的解决方案会引入隐藏成本，使代码库变得脆弱且难以维护。
魔法字符串：使用原始字符串如'ADMIN'或'POST'作为角色或请求方法是定时炸弹。单个拼写错误（'ADMNIN'）会创建一个TypeScript无法捕获的bug。
重复逻辑：为每个API端点编写新的fetch函数（fetchUser、fetchArticle、fetchComment）会创建维护噩梦。认证逻辑的更改需要更新数十个文件。
类型漂移：你手动为API响应编写TypeScript interface。API发生变化——字段被重命名或删除。你的测试仍然编译，但在运行时失败，因为你的类型撒谎了。
负载混淆：你对创建新文章和更新标题都使用相同的大Article类型。这令人困惑且效率低下。
这些小问题会累积，导致一个难以重构且令人恐惧的框架。
🛠️ 解决方案，第1部分：枚举实现坚如磐石的常量
消除"魔法字符串"bug的最快方法是使用枚举。枚举是命名常量的受限集合。
脆弱的方式（魔法字符串）
想象一个分配角色的函数。字符串中的拼写错误会静默通过TypeScript。
// 🚨 这是"之前" - 等待发生的bug 🚨
function assignRole(username: string, role: string) {
// 如果有人传递'admn'或'editorr'怎么办？
console.log(`分配角色: ${role} 给 ${username}`);
}
// 简单的拼写错误意味着这段代码在逻辑上有缺陷，但TS不知道
assignRole('idavidov', 'admnin'); // 糟糕！
健壮的修复（枚举）
通过定义UserRole枚举，我们强制开发者从有效选项列表中选择，给我们自动完成和编译时安全性。
// ✅ 这是"之后" - 类型安全且清晰 ✅
export enum UserRole {
ADMIN = 'admin',
EDITOR = 'editor',
VIEWER = 'viewer',
}
function assignRole(username: string, role: UserRole) {
console.log(`分配角色: ${role} 给 ${username}`);
}
// 1. 无拼写错误：如果UserRole.ADMNIN存在，TS会抛出错误
// 2. 自动完成：你的编辑器会建议ADMIN、EDITOR或VIEWER
assignRole('idavidov', UserRole.ADMIN);
经验法则：如果你有一组固定的相关字符串，使用枚举。
🚀 解决方案，第2部分：泛型实现最大可重用性
泛型可以说是编写可扩展代码最强大的功能。它们允许你编写可以与任何类型一起工作的函数，而不牺牲类型安全性。完美的用例是可重用的API请求函数。
重复的方式（无泛型）
没有泛型，你最终会为每个API端点编写几乎相同的函数。
// 🚨 "之前" - 大量重复代码 🚨
async function fetchArticle(id: string): Promise<ArticleResponse> {
const res = await request.get(`/api/articles/${id}`);
return await res.json();
}
async function fetchUser(id: string): Promise<UserResponse> {
const res = await request.get(`/api/users/${id}`);
return await res.json();
}
可扩展的修复（泛型函数）
我们可以编写一个函数apiRequest，它可以获取任何资源并返回强类型响应。魔法是`<T>占位符。
// ✅ "之后" - 单个、可重用、类型安全的函数 ✅
// 我们定义一个接受泛型类型`T`的函数
// 它返回一个Promise，其主体将是类型`T`
async function apiRequest<T = unknown>({
method,
url,
}: // ... 其他参数
ApiRequestParams): Promise<ApiRequestResponse<T>> {
const response = await apiRequestOriginal({
/* ... 实现细节 ... */
});
return {
status: response.status,
body: response.body as T, // 我们告诉TS在这里信任我们
};
}
当我们调用这个函数时，我们指定T应该是什么。
// T变成ArticleResponse。'body'常量现在完全类型化了！
const { body } = await apiRequest<ArticleResponse>({
method: 'GET',
url: 'api/articles/my-article',
});
// 我们现在可以使用完整的自动完成访问body.article.title
console.log(body.article.title);
🛡️ 解决方案，第3部分：Zod & z.infer实现端到端安全性
我们已经解决了代码重复。现在让我们解决"类型漂移"。你数据的最终真相来源是API本身。Zod是一个TypeScript库，它让我们创建一个在运行时验证真实API响应的模式，而z.infer让我们从同一个模式创建编译时TypeScript类型。
一个模式。两个好处。零漂移。
首先，为你的API响应定义一个模式。这是一个描述数据形状的实际JavaScript对象。
// 1. 用Zod定义运行时模式
export const ArticleResponseSchema = z.object({
article: z.object({
slug: z.string(),
title: z.string(),
description: z.string(),
body: z.string(),
author: z.object({
username: z.string(),
// ... 其他作者字段
}),
}),
});
接下来，使用z.infer的魔法从模式创建TypeScript类型，无需任何额外工作。
// 2. 直接从模式推断TypeScript类型
export type ArticleResponse = z.infer<typeof ArticleResponseSchema>;
// 无需手动编写这个！
// interface ArticleResponse {
// article: {
// slug: string;
// title: string;
// ...
// }
// }
现在，在你的测试中，你两者都使用。Zod模式验证实时数据，推断的类型给你自动完成和静态分析。
// 3. 在测试中使用两者以获得100%的信心
await test.step('验证创建文章', async () => {
const { status, body } = await apiRequest<ArticleResponse>({
/* ... 请求参数 ... */
});
// 运行时检查：API响应是否匹配我们的模式？
// 如果API发生变化，这将失败，立即捕获bug
expect(ArticleResponseSchema.parse(body)).toBeTruthy();
// 编译时安全性：我们现在可以自信地使用'body'
const articleId = body.article.slug;
expect(status).toBe(201);
});
🛠️ 解决方案，第4部分：typeof和工具类型实现灵活性
有时你需要简单、临时对象的类型，或者你需要为API更新负载等事情创建现有类型的轻微变体。
typeof：从运行时对象创建类型
如果你的代码中有一个常量对象，你可以使用typeof创建一个完美匹配其形状的类型。
// 定义默认负载的运行时对象
const defaultArticlePayload = {
article: {
title: '我的默认标题',
description: '一篇很棒的文章',
body: '内容...',
tagList: ['testing', 'playwright'],
},
};
// 创建一个完全匹配对象形状的类型
type ArticlePayload = typeof defaultArticlePayload;
// 这个函数现在只接受具有该确切形状的对象
function createArticle(payload: ArticlePayload) {
// ...
}
Partial和Pick：从其他类型创建类型
使用我们从Zod的ArticleResponse类型，如果我们想更新文章怎么办？我们可能只需要发送几个字段，而不是全部。工具类型让我们可以即时创建这些变体。
Partial<T>：使T中的所有字段可选
Pick<T, K>：通过从T中选择几个键K创建新类型
// 我们的原始类型，其中所有字段都是必需的
// type Article = { slug: string; title: string; body: string; ... }
type Article = z.infer<typeof ArticleResponseSchema>['article'];
// ✅ 场景1：更新负载，其中任何字段都是可选的
// 这创建了一个类型如：{ title?: string; body?: string; ... }
type UpdateArticlePayload = Partial<Article>;
// ✅ 场景2：表示唯一标识符的类型
// 这创建了类型：{ slug: string; }
type ArticleLocator = Pick<Article, 'slug'>;
5个模式总结
🚀 你的使命：构建一个牢不可破的框架
你现在已经装备了在最健壮、企业级测试自动化框架中使用的模式。回到你自己的项目，寻找升级的机会：
寻找魔法字符串：找到任何硬编码字符串（'admin'、'success'、'POST'）并用枚举替换它们
模式化你的端点：选择你最关键的API端点，为它编写Zod模式，并使用z.infer生成类型。在测试中应用它
用泛型重构：识别两个或更多重复函数（如API调用）并将它们重构为单个、可重用的泛型函数
创建智能负载：寻找POST或PATCH请求，使用Partial或Pick等工具类型创建精确、最小的负载
采用这些高级模式是将你的测试框架从简单工具转变为强大、可扩展和真正可靠的工程资产的最后一步。
实际应用示例
1. 完整的API客户端实现
// 定义API请求参数类型
interface ApiRequestParams {
method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
url: string;
body?: unknown;
headers?: Record<string, string>;
}
// 定义API响应类型
interface ApiRequestResponse<T> {
status: number;
body: T;
headers: Record<string, string>;
}
// 泛型API请求函数
async function apiRequest<T = unknown>({
method,
url,
body,
headers = {},
}: ApiRequestParams): Promise<ApiRequestResponse<T>> {
const response = await fetch(url, {
method,
headers: {
'Content-Type': 'application/json',
...headers,
},
body: body ? JSON.stringify(body) : undefined,
});
const responseBody = await response.json();
return {
status: response.status,
body: responseBody as T,
headers: Object.fromEntries(response.headers.entries()),
};
}
2. 完整的Zod模式示例
import { z } from 'zod';
// 用户模式
export const UserSchema = z.object({
id: z.number(),
username: z.string().min(3),
email: z.string().email(),
role: z.enum(['admin', 'editor', 'viewer']),
createdAt: z.string().datetime(),
updatedAt: z.string().datetime(),
});
// 文章模式
export const ArticleSchema = z.object({
id: z.number(),
slug: z.string(),
title: z.string().min(1),
description: z.string(),
body: z.string(),
author: UserSchema,
tagList: z.array(z.string()),
createdAt: z.string().datetime(),
updatedAt: z.string().datetime(),
});
// 文章响应模式
export const ArticleResponseSchema = z.object({
article: ArticleSchema,
});
// 文章列表响应模式
export const ArticlesResponseSchema = z.object({
articles: z.array(ArticleSchema),
articlesCount: z.number(),
});
// 推断类型
export type User = z.infer<typeof UserSchema>;
export type Article = z.infer<typeof ArticleSchema>;
export type ArticleResponse = z.infer<typeof ArticleResponseSchema>;
export type ArticlesResponse = z.infer<typeof ArticlesResponseSchema>;
3. 完整的测试示例
import { test, expect } from '@playwright/test';
import { apiRequest } from '../utils/api-client';
import {
ArticleResponseSchema,
ArticleResponse,
UpdateArticlePayload
} from '../schemas/article';
test.describe('文章API测试', () => {
test('应该创建新文章', async () => {
const newArticle = {
article: {
title: '测试文章',
description: '这是一个测试文章',
body: '文章内容...',
tagList: ['testing', 'automation'],
},
};
const { status, body } = await apiRequest<ArticleResponse>({
method: 'POST',
url: '/api/articles',
body: newArticle,
});
// 运行时验证
expect(ArticleResponseSchema.parse(body)).toBeTruthy();
// 编译时类型安全
expect(status).toBe(201);
expect(body.article.title).toBe('测试文章');
expect(body.article.author.username).toBeDefined();
});
test('应该更新文章', async () => {
const updatePayload: UpdateArticlePayload = {
title: '更新的标题',
description: '更新的描述',
};
const { status, body } = await apiRequest<ArticleResponse>({
method: 'PUT',
url: '/api/articles/test-article',
body: { article: updatePayload },
});
expect(status).toBe(200);
expect(body.article.title).toBe('更新的标题');
});
});
4. 工具类型的高级用法
// 从现有类型创建新类型
type CreateArticlePayload = Pick<Article, 'title' | 'description' | 'body' | 'tagList'>;
type ArticleSummary = Pick<Article, 'id' | 'title' | 'description' | 'author'>;
type ArticleUpdatePayload = Partial<CreateArticlePayload>;
// 组合工具类型
type RequiredArticleFields = Required<Pick<Article, 'title' | 'body'>>;
type OptionalArticleFields = Partial<Omit<Article, 'id' | 'createdAt' | 'updatedAt'>>;
// 条件类型
type ApiResponse<T> = {
data: T;
status: 'success' | 'error';
message?: string;
};
type SuccessResponse<T> = ApiResponse<T> & { status: 'success' };
type ErrorResponse = ApiResponse<never> & { status: 'error'; message: string };
🙏🏻 感谢阅读！ 构建健壮、可扩展的自动化框架是一个最好一起进行的旅程。如果你觉得这篇文章有帮助，考虑加入一个不断增长的QA专业人士社区🚀，他们热衷于掌握现代测试。
通过注册通讯加入社区并获取最新文章和技巧。