Playwright + TypeScript Thực chiến
Trang chủ / Module 2
🔷 Module 2 / 15 · 1 tuần

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.

TypeScriptasync/awaitTypes
📌 Vì sao module này quan trọng

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ỗiHậu quảSửa
Quên await trước action/expectTest pass giả hoặc fail ở chỗ khácLint no-floating-promises
array.forEach(async ...)forEach không chờ; các thao tác chạy lộn xộnfor...of với await, hoặc Promise.all(array.map(...))
Promise.all cho thao tác trên cùng một pageThao tác UI chen nhauChỉ song song hoá việc độc lập (API, nhiều context)
try/catch nuốt lỗi của expectTest luôn passKhô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ĩaDùng trong test để
Partial<T>Mọi trường thành optionalTham số ghi đè của factory
Pick<T, K> / Omit<T, K>Lấy / bỏ một số trườngPayload tạo mới = model bỏ id, createdAt
Record<K, V>Object với khoá kiểu KBả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àmLấ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ánhVì saoThay bằng
anyTắ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ểuKiểm tra tường minh và báo lỗi có nghĩa
as Order trên dữ liệu ngoàiCompiler tin, nhưng dữ liệu thật có thể khácXác thực bằng schema (mục sau)
// @ts-ignoreChe 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

Kiểu hoá toàn bộ dữ liệu test của dự án

(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

✅ 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