TypeScript cho Test Engineer
Phần TypeScript thật sự cần cho test automation: async/await không sai, kiểu cho dữ liệu test và page object, union/generic/utility type, và các lỗi kiểu thường gặp.
Bạn không cần là chuyên gia TypeScript để viết test tốt, nhưng cần vững một phần cụ thể của nó. Thiếu
phần đó dẫn tới hai thái cực: test đầy any (mất hết lợi ích của kiểu, lỗi chỉ lộ khi chạy), hoặc
vật lộn với lỗi biên dịch mà không hiểu. Kiểu dữ liệu tốt là tài liệu sống của bộ test: IDE gợi ý đúng
phương thức của page object, báo ngay khi API đổi trường, và đồng nghiệp mới đọc chữ ký hàm là hiểu cách dùng.
🎯 Mục tiêu học tập
- Dùng đúng async/await và Promise.all; nhận diện race condition do thiếu await
- Định nghĩa kiểu cho dữ liệu test bằng type/interface, union literal, và optional
- Dùng utility type (Partial, Pick, Omit, Record) và generic cho factory và API client
- Thu hẹp kiểu an toàn thay vì ép kiểu; tránh any và dấu ! không cần thiết
- Xác thực dữ liệu runtime từ API bằng schema (zod) để kiểu khớp với thực tế
async/await: hiểu đúng để không flaky
Mọi thao tác Playwright đều bất đồng bộ và trả về Promise. Ba mẫu hình cần thuộc:
// 1. Tuần tự: thao tác sau phụ thuộc thao tác trước
await page.getByLabel('Email').fill('an@example.com');
await page.getByRole('button', { name: 'Đăng nhập' }).click();
// 2. Đồng thời, độc lập: chuẩn bị dữ liệu qua API
const [user, product] = await Promise.all([
api.users.create(newUser()),
api.products.create(newProduct()),
]);
// 3. Bắt một sự kiện do hành động gây ra: đăng ký chờ TRƯỚC khi hành động
const responsePromise = page.waitForResponse(r => r.url().includes('/api/orders') && r.request().method() === 'POST');
await page.getByRole('button', { name: 'Đặt hàng' }).click();
const response = await responsePromise;
Mẫu thứ ba là chỗ hay sai nhất. Nếu viết await click() rồi mới await waitForResponse(),
response có thể đã về trước khi bạn bắt đầu chờ, và test treo đến timeout — nhưng chỉ thỉnh
thoảng, trên máy nhanh. Quy tắc: tạo Promise chờ trước, hành động, rồi mới await Promise.
Áp dụng cho waitForResponse, waitForRequest, waitForEvent('popup'),
waitForEvent('download').
| Lỗi | Hậu quả | Sửa |
|---|---|---|
Quên await trước action/expect | Test pass giả hoặc fail ở chỗ khác | Lint no-floating-promises |
array.forEach(async ...) | forEach không chờ; các thao tác chạy lộn xộn | for...of với await, hoặc Promise.all(array.map(...)) |
Promise.all cho thao tác trên cùng một page | Thao tác UI chen nhau | Chỉ song song hoá việc độc lập (API, nhiều context) |
try/catch nuốt lỗi của expect | Test luôn pass | Không bọc assertion trong try/catch; dùng expect.soft nếu muốn đi tiếp |
Kiểu cho dữ liệu test
// Union literal: tập giá trị đóng — IDE gợi ý, gõ sai là lỗi biên dịch
type Role = 'admin' | 'manager' | 'staff' | 'customer';
type OrderStatus = 'pending' | 'paid' | 'shipped' | 'delivered' | 'refunded';
interface User {
id: string;
email: string;
fullName: string;
role: Role;
phone?: string; // optional
readonly createdAt: string; // không được gán lại
}
interface Order {
id: string;
customerId: User['id']; // lấy kiểu từ trường khác — đổi một chỗ, cập nhật mọi nơi
items: OrderItem[];
status: OrderStatus;
total: number;
}
// as const + satisfies: hằng số vừa có kiểu chính xác vừa được kiểm tra hình dạng
const ROUTES = {
login: '/login',
cart: '/cart',
order: (id: string) => `/orders/${id}`,
} as const;
const ACCOUNTS = {
admin: { email: 'admin@test.local', role: 'admin' },
customer: { email: 'customer@test.local', role: 'customer' },
} satisfies Record<string, Pick<User, 'email' | 'role'>>;
Dùng type hay interface? Cả hai đều được cho object; chọn một quy ước và giữ
nhất quán. Union, tuple, và kiểu tính toán thì bắt buộc dùng type.
Utility type và generic trong test
| Utility type | Ý nghĩa | Dùng trong test để |
|---|---|---|
Partial<T> | Mọi trường thành optional | Tham số ghi đè của factory |
Pick<T, K> / Omit<T, K> | Lấy / bỏ một số trường | Payload tạo mới = model bỏ id, createdAt |
Record<K, V> | Object với khoá kiểu K | Bảng tra theo role, theo môi trường |
Awaited<T> / ReturnType<F> | Kiểu sau khi await / kiểu trả về của hàm | Lấy kiểu từ hàm có sẵn thay vì khai báo lại |
type NewUser = Omit<User, 'id' | 'createdAt'>;
// Factory: giá trị mặc định hợp lệ + ghi đè có kiểu
let seq = 0;
export function newUser(overrides: Partial<NewUser> = {}): NewUser {
const n = `${Date.now()}-${process.pid}-${seq++}`; // duy nhất giữa các worker chạy song song
return {
email: `user-${n}@test.local`,
fullName: `Người dùng ${n}`,
role: 'customer',
...overrides,
};
}
newUser({ role: 'admin' }); // hợp lệ
newUser({ role: 'superuser' }); // lỗi biên dịch: không thuộc Role
// Generic: một hàm gọi API dùng cho mọi kiểu dữ liệu
async function getJson<T>(request: APIRequestContext, url: string): Promise<T> {
const res = await request.get(url);
expect(res, `GET ${url}`).toBeOK();
return (await res.json()) as T;
}
const order = await getJson<Order>(request, `/api/orders/${id}`);
order.status; // IDE biết đây là OrderStatus
Thu hẹp kiểu thay vì ép kiểu
| Tránh | Vì sao | Thay bằng |
|---|---|---|
any | Tắt toàn bộ kiểm tra kiểu, lây lan sang mọi thứ chạm vào nó | unknown rồi thu hẹp; hoặc khai báo kiểu thật |
value! (non-null assertion) | Nói với compiler "tin tôi" — khi sai thì lỗi runtime khó hiểu | Kiểm tra tường minh và báo lỗi có nghĩa |
as Order trên dữ liệu ngoài | Compiler tin, nhưng dữ liệu thật có thể khác | Xác thực bằng schema (mục sau) |
// @ts-ignore | Che mọi lỗi trên dòng đó, kể cả lỗi mới phát sinh | // @ts-expect-error kèm lý do |
// textContent() trả về string | null
const text = await page.getByTestId('total').textContent();
const bad = parseInt(text!); // null → NaN, lỗi mơ hồ ở chỗ khác
if (text === null) throw new Error('Không đọc được tổng tiền');
const total = Number(text.replace(/[^\d]/g, '')); // ở đây text chắc chắn là string
// Tốt hơn nữa: không đọc text ra rồi tự so — để assertion tự chờ và tự báo lỗi rõ
await expect(page.getByTestId('total')).toHaveText('1.250.000 ₫');
Với noUncheckedIndexedAccess, items[0] có kiểu Item | undefined —
hơi phiền, nhưng nó chặn đúng lớp lỗi "mảng rỗng" hay gặp trong test dùng dữ liệu động.
Xác thực dữ liệu runtime bằng schema
Kiểu TypeScript biến mất khi chạy. await res.json() as Order không kiểm tra gì cả. Dùng
thư viện schema (zod) để một định nghĩa vừa sinh ra kiểu, vừa xác thực dữ liệu thật —
đồng thời bạn có luôn một contract test nhẹ cho API:
import { z } from 'zod';
export const OrderSchema = z.object({
id: z.string().uuid(),
status: z.enum(['pending', 'paid', 'shipped', 'delivered', 'refunded']),
total: z.number().nonnegative(),
items: z.array(z.object({ sku: z.string(), quantity: z.number().int().positive() })).min(1),
});
export type Order = z.infer<typeof OrderSchema>; // kiểu sinh từ schema: một nguồn sự thật
test('API trả đơn hàng đúng hợp đồng', async ({ request }) => {
const res = await request.get(`/api/orders/${orderId}`);
expect(res).toBeOK();
const order = OrderSchema.parse(await res.json()); // sai hình dạng → lỗi chỉ rõ trường nào
expect(order.status).toBe('paid');
});
Cùng kỹ thuật áp dụng cho biến môi trường: xác thực process.env một lần khi khởi động, để
thiếu BASE_URL thì báo lỗi rõ ràng ngay thay vì fail bí ẩn ở test thứ 40.
// utils/env.ts
const Env = z.object({
BASE_URL: z.string().url(),
TEST_USER_PASSWORD: z.string().min(1),
CI: z.string().optional(),
});
export const env = Env.parse(process.env);
🏋️ Bài tập thực hành
(1) Định nghĩa kiểu cho 3-4 thực thể chính của ứng dụng bạn test (User, Product, Order...) với
union literal cho mọi trường có tập giá trị đóng. (2) Viết factory newX(overrides) cho từng
thực thể, sinh dữ liệu duy nhất giữa các worker. (3) Viết schema zod cho hai response API quan trọng nhất và
một test kiểm tra hợp đồng; thử cố ý sửa schema sai để xem thông báo lỗi. (4) Viết utils/env.ts
xác thực biến môi trường. (5) Bật @typescript-eslint/no-explicit-any và
no-non-null-assertion, sửa hết cảnh báo. (6) Viết một test dùng đúng mẫu "tạo Promise chờ
trước, hành động sau" cho waitForResponse, rồi cố ý đảo thứ tự và chạy
--repeat-each=30 để quan sát.
📚 Tài nguyên học tập
-
TypeScript HandbookTài liệu chính thức; đọc kỹ Everyday Types, Narrowing, Generics, Utility TypesDocs
-
TypeScript — Utility TypesTra cứu Partial, Pick, Omit, Record, Awaited...Docs
-
Zod — DocumentationSchema xác thực runtime kèm suy luận kiểuDocs
-
typescript-eslint — no-floating-promisesQuy tắc lint quan trọng nhất cho code test bất đồng bộDocs
-
Total TypeScript — TutorialsBài tập TypeScript tương tác miễn phíKhoá học
✅ Tự đánh giá hoàn thành
- Viết đúng ba mẫu async: tuần tự, Promise.all, và chờ sự kiện trước khi hành động
- Dữ liệu test có kiểu với union literal; không còn any trong dự án
- Factory dùng Partial và sinh dữ liệu duy nhất khi chạy song song
- Dùng thu hẹp kiểu thay cho ! và as trên dữ liệu không chắc chắn
- Response API quan trọng và biến môi trường được xác thực bằng schema