GitHub Actions cho Next.js: test tự chạy mỗi lần đẩy code
GitHub Actions cho Next.js: kiểm xem bộ test Vitest có thật sự bắt được lỗi không, rồi viết workflow chạy kiểm kiểu và test mỗi lần đẩy code lên nhánh.
Muốn bớt sợ sửa code, bạn cần bộ test thật sự bắt được lỗi và một workflow GitHub Actions tự chạy nó mỗi lần đẩy code. Bạn có tin bộ test của mình không? Cùng mình thử làm hỏng code để kiểm nhé.
Mình sợ sửa code, vậy test giúp được gì?
Ở tập trước của Xây blog với Next.js và Supabase, blog có thêm form đăng ký bản tin, và mình kết thúc bằng một nỗi lo khá thật: sửa hàm kiểm tra email thì có làm hỏng form hủy đăng ký không? Cách trả lời nhanh nhất là có một bộ test chạy trong vài giây và nói "chỗ khác vẫn ổn".
Mình chọn bốn hàm thuần của form đăng ký làm ví dụ, vì chúng nhỏ nhưng có đủ loại ranh giới. File src/ban-tin.ts dưới đây là bản rút gọn từ code của blog. Bốn hàm này làm gì: normalizeEmail làm sạch email, emailProblem cho biết email sai ở đâu, looksAutomated đoán xem lượt gửi có phải của robot không (ô bẫy bị điền, hoặc điền form nhanh hơn 1,5 giây), và signupSource chỉ nhận đường dẫn trong site.
export const MAX_EMAIL_LENGTH = 254;
const EMAIL = /^[^@\s]+@[^@\s]+\.[^@\s]+$/;
/** Người điền form mất vài giây, robot mất vài mili giây: nhanh hơn mức này thì bỏ qua. */
export const MIN_FILL_MS = 1500;
export function normalizeEmail(value: string): string {
return value.trim().toLowerCase();
}
export function emailProblem(value: string): "emailMissing" | "emailInvalid" | null {
const email = normalizeEmail(value);
if (!email) return "emailMissing";
if (email.length > MAX_EMAIL_LENGTH || !EMAIL.test(email)) return "emailInvalid";
return null;
}
export function looksAutomated({ honeypot, startedAt, now }: { honeypot: string; startedAt: string; now: number }): boolean {
if (honeypot.trim()) return true;
const started = Number(startedAt);
if (!Number.isFinite(started) || started <= 0) return false; // không có mốc giờ từ JavaScript thì không phạt người dùng
const elapsed = now - started;
return elapsed >= 0 && elapsed < MIN_FILL_MS;
}
export function signupSource(value: string): string {
return /^\/[\w\-/]*$/.test(value) ? value.slice(0, 120) : "";
}Lần đầu viết test, mình làm cái mà hầu như ai cũng làm: mỗi hàm một ví dụ chạy đúng. Chúng nằm trong src/ban-tin.so-khai.test.ts và dùng Vitest, trình chạy test mà chính blog này đang dùng.
import { describe, expect, it } from "vitest";
import { emailProblem, looksAutomated, normalizeEmail, signupSource } from "./ban-tin.ts";
describe("ban-tin (sơ khai)", () => {
it("chuẩn hóa email", () => {
expect(normalizeEmail(" An@Example.com ")).toBe("an@example.com");
});
it("email hợp lệ không có vấn đề", () => {
expect(emailProblem("an@example.com")).toBeNull();
});
it("email sai bị báo", () => {
expect(emailProblem("khong-co-a-cong")).toBe("emailInvalid");
});
it("robot điền ô bẫy bị nhận ra", () => {
expect(looksAutomated({ honeypot: "http://spam", startedAt: "0", now: 10_000 })).toBe(true);
});
it("nguồn đăng ký là đường dẫn trong site", () => {
expect(signupSource("/bai-viet/abc")).toBe("/bai-viet/abc");
});
});Cả năm test đều xanh. Nhưng xanh thì chưa nói gì về chuyện chúng có bảo vệ được code hay không.
Làm sao biết bộ test có bắt được lỗi?
Cách mình dùng là tự làm hỏng code một chỗ nhỏ, rồi chạy test. Nếu không test nào đỏ thì lỗi đó có thể vào code thật mà không ai hay. Người ta gọi kỹ thuật này là mutation testing; bản đầy đủ có công cụ tự sinh hàng trăm lỗi, còn mình làm tay mười lỗi cho dễ hiểu. Script lam-hong.ts sửa src/ban-tin.ts một chỗ, chạy Vitest trên đúng một file test, ghi lại kết quả, và luôn trả code về nguyên trạng ở cuối (khối finally). Đây là phần đáng chú ý của nó:
const LOI = [
{ mota: "bỏ .toLowerCase() khi chuẩn hóa email", tim: "value.trim().toLowerCase()", thay: "value.trim()" },
{ mota: "bỏ .trim() khi chuẩn hóa email", tim: "value.trim().toLowerCase()", thay: "value.toLowerCase()" },
{ mota: "email dài đúng 254 ký tự bị coi là sai (> thành >=)", tim: "email.length > MAX_EMAIL_LENGTH", thay: "email.length >= MAX_EMAIL_LENGTH" },
{ mota: "cho phép hai dấu @ trong email", tim: "/^[^@\\s]+@[^@\\s]+\\.[^@\\s]+$/", thay: "/^[^\\s]+@[^@\\s]+\\.[^@\\s]+$/" },
{ mota: "ô bẫy chỉ có khoảng trắng bị coi là robot", tim: "if (honeypot.trim()) return true;", thay: "if (honeypot) return true;" },
{ mota: "đúng 1,5 giây bị coi là robot (< thành <=)", tim: "elapsed < MIN_FILL_MS", thay: "elapsed <= MIN_FILL_MS" },
{ mota: "đồng hồ lệch (mốc giờ ở tương lai) bị coi là robot", tim: "elapsed >= 0 && elapsed", thay: "elapsed" },
{ mota: "mốc giờ 0 hoặc âm không còn được bỏ qua", tim: "!Number.isFinite(started) || started <= 0", thay: "!Number.isFinite(started)" },
{ mota: "nguồn đăng ký không còn bị cắt ở 120 ký tự", tim: "value.slice(0, 120)", thay: "value" },
{ mota: "nguồn đăng ký nhận cả địa chỉ ngoài site (bỏ ^)", tim: "/^\\/[\\w\\-/]*$/", thay: "/\\/[\\w\\-/]*$/" },
];
for (const { mota, tim, thay } of LOI) {
writeFileSync(FILE, GOC.replace(tim, () => thay)); // sửa một chỗ
const bat = chay(fileTest).status !== 0; // test đỏ nghĩa là lỗi bị bắt
console.log(`${bat ? "bắt được " : "LỌT QUA "} ${mota}`);
}Mình chạy node lam-hong.ts src/ban-tin.so-khai.test.ts:
bắt được bỏ .toLowerCase() khi chuẩn hóa email
bắt được bỏ .trim() khi chuẩn hóa email
LỌT QUA email dài đúng 254 ký tự bị coi là sai (> thành >=)
LỌT QUA cho phép hai dấu @ trong email
LỌT QUA ô bẫy chỉ có khoảng trắng bị coi là robot
LỌT QUA đúng 1,5 giây bị coi là robot (< thành <=)
LỌT QUA đồng hồ lệch (mốc giờ ở tương lai) bị coi là robot
LỌT QUA mốc giờ 0 hoặc âm không còn được bỏ qua
LỌT QUA nguồn đăng ký không còn bị cắt ở 120 ký tự
LỌT QUA nguồn đăng ký nhận cả địa chỉ ngoài site (bỏ ^)
src/ban-tin.so-khai.test.ts: 2/10 lỗi bị bắt, 8 lọt qua.Bộ test xanh của mình chỉ bắt được 2 trong 10 lỗi. Tám lỗi còn lại, như cho phép hai dấu @ hay phạt oan người điền form đúng 1,5 giây, đều sẽ vào code thật mà CI vẫn báo xanh. Đó chính xác là nỗi sợ ở đầu bài, chỉ khác là bây giờ mình có con số.
Viết thêm test ở sát ranh giới
Chỗ các lỗi lọt qua có điểm chung: chúng nằm ở ranh giới (254 hay 255, 1.499 ms hay 1.500 ms) hoặc ở ca đặc biệt (hai dấu @, ô bẫy toàn khoảng trắng). Ví dụ "đường đẹp" không bao giờ chạm tới các chỗ đó. Vì vậy mỗi quy tắc mình thêm ví dụ ngay hai bên ranh giới, và dùng it.each để mỗi dòng "đầu vào → kết quả" là một ca có tên. Đây là src/ban-tin.test.ts:
import { describe, expect, it } from "vitest";
import { MAX_EMAIL_LENGTH, MIN_FILL_MS, emailProblem, looksAutomated, normalizeEmail, signupSource } from "./ban-tin.ts";
describe("normalizeEmail", () => {
it("bỏ khoảng trắng hai đầu và hạ chữ thường", () => {
expect(normalizeEmail(" An@Example.com ")).toBe("an@example.com");
});
it("giữ nguyên dấu + dùng làm nhãn", () => {
expect(normalizeEmail("an+blog@example.com")).toBe("an+blog@example.com");
});
});
describe("emailProblem", () => {
it.each([
["an@example.com", null],
["AN@EXAMPLE.COM ", null],
["", "emailMissing"],
[" ", "emailMissing"],
["khong-co-a-cong", "emailInvalid"],
["an@khong-co-cham", "emailInvalid"],
["an @example.com", "emailInvalid"],
["a@b@example.com", "emailInvalid"],
])("%j → %j", (vao, ra) => {
expect(emailProblem(vao)).toBe(ra);
});
it("email dài đúng 254 ký tự thì hợp lệ, 255 thì không", () => {
const duoi = "@example.com";
const dung = "a".repeat(MAX_EMAIL_LENGTH - duoi.length) + duoi;
expect(dung).toHaveLength(254);
expect(emailProblem(dung)).toBeNull();
expect(emailProblem("a" + dung)).toBe("emailInvalid");
});
});
describe("looksAutomated", () => {
const luc = 1_000_000;
it("ô bẫy có chữ là robot, dù điền chậm", () => {
expect(looksAutomated({ honeypot: "http://spam", startedAt: String(luc - 60_000), now: luc })).toBe(true);
});
it("ô bẫy chỉ có khoảng trắng thì không tính", () => {
expect(looksAutomated({ honeypot: " ", startedAt: String(luc - 60_000), now: luc })).toBe(false);
});
it("điền nhanh hơn 1,5 giây là robot, đúng 1,5 giây thì không", () => {
expect(looksAutomated({ honeypot: "", startedAt: String(luc - (MIN_FILL_MS - 1)), now: luc })).toBe(true);
expect(looksAutomated({ honeypot: "", startedAt: String(luc - MIN_FILL_MS), now: luc })).toBe(false);
});
it("không có mốc giờ thì không phạt người dùng", () => {
for (const startedAt of ["", "abc", "0", "-5"]) {
expect(looksAutomated({ honeypot: "", startedAt, now: luc })).toBe(false);
}
});
it("mốc giờ nằm trong tương lai (đồng hồ lệch) thì không phạt", () => {
expect(looksAutomated({ honeypot: "", startedAt: String(luc + 5_000), now: luc })).toBe(false);
});
});
describe("signupSource", () => {
it.each([
["/bai-viet/abc", "/bai-viet/abc"],
["/", "/"],
["https://xau.com/", ""],
["//xau.com", ""],
["bai-viet", ""],
["/co khoang trang", ""],
])("%j → %j", (vao, ra) => {
expect(signupSource(vao)).toBe(ra);
});
it("cắt ở 120 ký tự", () => {
expect(signupSource("/" + "a".repeat(300))).toHaveLength(120);
});
});Mỗi ca ngoài đường đẹp có một lý do. Dòng "an @example.com" có từ vì khoảng trắng giữa email là lỗi dễ gặp khi dán. "https://xau.com/" và "//xau.com" có từ vì signupSource không được để địa chỉ ngoài site lọt vào cột lưu nguồn đăng ký. Còn các số MIN_FILL_MS - 1 và MIN_FILL_MS có từ để ghim đúng ranh giới 1,5 giây. Chạy lại script làm hỏng:
bắt được bỏ .toLowerCase() khi chuẩn hóa email
bắt được bỏ .trim() khi chuẩn hóa email
bắt được email dài đúng 254 ký tự bị coi là sai (> thành >=)
bắt được cho phép hai dấu @ trong email
bắt được ô bẫy chỉ có khoảng trắng bị coi là robot
bắt được đúng 1,5 giây bị coi là robot (< thành <=)
bắt được đồng hồ lệch (mốc giờ ở tương lai) bị coi là robot
LỌT QUA mốc giờ 0 hoặc âm không còn được bỏ qua
bắt được nguồn đăng ký không còn bị cắt ở 120 ký tự
bắt được nguồn đăng ký nhận cả địa chỉ ngoài site (bỏ ^)
src/ban-tin.test.ts: 9/10 lỗi bị bắt, 1 lọt qua.Từ 2 lên 9. Còn một lỗi lọt, và mình muốn nói rõ vì sao mình để nó lại. Dòng started <= 0 trong looksAutomated chặn mốc giờ bằng 0 hoặc âm. Nhưng nếu bỏ dòng đó, mốc giờ 0 vẫn cho elapsed bằng cả triệu mili giây (vì now là giờ hiện tại), và con số đó lớn hơn 1,5 giây nên hàm vẫn trả false. Nói cách khác, với giờ thật thì dòng đó gần như thừa, và không test nào phân biệt được nó với phiên bản không có nó. Mình có thể viết một test với now nhỏ bất thường để ép nó đỏ, nhưng đó là một tình huống không xảy ra ngoài đời, nên mình thấy không đáng. Quyết định giữ hay bỏ dòng đó là của bạn.
Chạy test mỗi lần đẩy code bằng GitHub Actions
Bộ test tốt đến mấy cũng vô dụng nếu người đẩy code quên chạy nó. Vì vậy mình đưa nó vào CI (continuous integration), nghĩa là một máy chủ của GitHub tự chạy một danh sách lệnh mỗi khi có code mới. Danh sách đó nằm trong một file YAML ở .github/workflows/. Đây là file ci.yml của tập này, mình lấy dạng từ workflow thật của blog rồi cắt bớt cho vừa một dự án nhỏ:
name: CI
on:
push:
branches:
- main
- "feat/**"
- "fix/**"
pull_request:
branches:
- main
permissions:
contents: read
# Một lần đẩy mới lên cùng nhánh hủy lượt chạy cũ đã lỗi thời.
concurrency:
group: ci-${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true
jobs:
chat-luong:
name: Kiểm tra chất lượng
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version-file: .node-version
cache: npm
- name: Cài thư viện đúng như package-lock.json
run: npm ci
- name: Kiểm tra kiểu
run: npm run typecheck
- name: Chạy test
run: npm testBốn chỗ trong file này đáng giải thích, vì mỗi chỗ có một lỗi mà ai cũng có thể gặp.
Khối on cho workflow chạy khi đẩy lên main, lên các nhánh feat/ và fix/, và khi mở pull request vào main. Nhờ vậy lỗi lộ ra ngay trên pull request, trước khi merge.
permissions: contents: read giới hạn token mà workflow nhận chỉ được đọc kho code. Quyền mặc định của token phụ thuộc vào cài đặt của kho, nên đặt rõ là cách chắc chắn nhất để một bước lạ không có quyền ghi.
concurrency với cancel-in-progress: true hủy lượt chạy cũ khi cùng nhánh có lượt mới. Bạn đẩy ba commit liên tiếp trong năm phút thì chỉ lượt cuối chạy tới nơi, và bạn không phải trả phút chạy cho hai lượt lỗi thời. Tài liệu về concurrency của GitHub nói nên dùng kiểu này cho các job kiểm tra (test, lint), vì chúng chạy lại an toàn, và không nên dùng cho deploy.
Và npm ci thay vì npm install. Hai lệnh này khác nhau ở một điểm quan trọng: npm ci cài đúng những gì package-lock.json ghi, và báo lỗi nếu package.json với lockfile không khớp, còn npm install thì lặng lẽ sửa lockfile cho khớp. Mình thử trên một bản sao: thêm is-odd vào package.json mà không cập nhật lockfile, rồi chạy npm ci.
npm error code EUSAGE
npm error
npm error `npm ci` can only install packages when your package.json and package-lock.json or npm-shrinkwrap.json are in sync. Please update your lock file with `npm install` before continuing.
npm error
npm error Missing: is-odd@3.0.1 from lock file
npm error Missing: is-number@6.0.0 from lock fileDừng ngay với một thông báo nói đúng chuyện gì sai. Trên CI, đó là điều bạn muốn: máy của đồng nghiệp và máy CI cài chính xác cùng phiên bản, nên "máy em chạy mà" khó xảy ra hơn.
Kiểm workflow trước khi đẩy
Có một cái khó chịu của CI: bạn chỉ biết file YAML sai khi đã đẩy lên và chờ GitHub báo đỏ. Mình không chạy được GitHub Actions trên máy, nhưng một số lỗi lặp đi lặp lại thì kiểm được bằng code: gọi npm run lint khi không có script lint, trỏ tới file .nvmrc không tồn tại, dùng npm install thay vì npm ci, quên permissions hay concurrency. Script kiem-ci.ts đọc file YAML bằng thư viện yaml và kiểm đúng năm điều đó so với package.json. Mình chạy nó trên workflow ở trên và trên một workflow cố ý viết sai (vi-du-loi/ci-loi.yml):
.github/workflows/ci.yml: không thấy lỗi
vi-du-loi/ci-loi.yml: 5 vấn đề
✗ Thiếu `permissions:`; mặc định token của workflow có thể có quyền ghi, hãy đặt `contents: read`.
✗ Thiếu `concurrency:`; mỗi lần đẩy mới sẽ chạy tiếp cả lượt cũ, tốn phút chạy.
✗ chat-luong: node-version-file trỏ tới ".nvmrc" nhưng file này không tồn tại.
✗ chat-luong: dùng `npm ci` thay vì `npm install`; npm install có thể sửa package-lock.json thay vì báo lệch.
✗ chat-luong: `npm run lint` nhưng package.json không có script "lint".Hãy đọc phần này đúng như nó là. Đây là năm quy tắc mình tự đặt, không phải một bộ kiểm tra đầy đủ cho GitHub Actions. Nó không biết gì về cú pháp biểu thức ${{ }}, quyền của từng uses, hay việc một action có tồn tại không. Mình dùng nó để bắt các lỗi mình đã tự gặp, không để thay việc chạy thật.
Blog này đang chạy CI như thế nào?
Workflow của tập này là bản thu nhỏ. Workflow thật của Tech Notes (file .github/workflows/ci.yml trong repo blog) có cùng khung on, permissions và concurrency, nhưng gồm hai job. Job governance chạy trước, kiểm các quy tắc của repo và quét bí mật. Job application-quality chỉ chạy khi governance xong, và chạy tuần tự: npm ci, npm run lint, npm run typecheck, npm test, npm run build rồi npm audit --audit-level=high. Tới lúc mình viết bài này, kho có 40 file test dùng Vitest.
Thỏa thuận làm việc của kho còn nói rõ một điều mình thấy quan trọng hơn cả file YAML: không merge khi bất kỳ check bắt buộc nào chưa qua, và không ai đẩy thẳng lên main. File workflow chỉ chạy lệnh; chính quy tắc "đỏ thì không merge" mới biến nó thành lưới an toàn. Nếu bạn làm một mình và vẫn bấm merge khi CI đỏ thì CI chỉ là đồ trang trí.
Những điều bài này chưa làm
Mình nói thẳng các giới hạn. Một, mình không chạy được GitHub Actions trên máy (không có công cụ chạy thử workflow cục bộ trong môi trường của mình), nên ci.yml của tập này chỉ được kiểm bằng kiem-ci.ts và bằng việc từng lệnh trong đó chạy đúng trên máy: npm run typecheck qua, npm test ra 32 test xanh. Mình chưa thấy nó chạy trên GitHub. Hai, bài này không có Playwright. Blog hiện chưa dùng Playwright, và mình không muốn viết về một công cụ mình chưa chạy trong dự án; các test ở đây đều là test của hàm thuần, chưa test được chuyện bấm nút trên trình duyệt. Ba, mười lỗi trong lam-hong.ts do mình chọn tay, nên "9 trên 10" không phải điểm số của bộ test, chỉ cho biết nó mạnh hơn bản đầu ở đúng những chỗ mình nghĩ tới. Công cụ mutation testing tự sinh lỗi sẽ tìm được nhiều chỗ hơn, nhưng mình chưa thử. Bốn, mình không đo độ phủ (coverage) của test.
Test xanh rồi, nhưng code vẫn chưa tới tay người đọc
Giờ mỗi pull request của blog đều qua một cổng: kiểm kiểu, test, build. Nhưng một cổng chỉ nói code này không làm hỏng những gì mình đã kiểm. Nó không nói trang thật có chạy ổn trên môi trường thật hay không, và cũng không cho bạn cách quay lại khi bản mới lên rồi mới thấy lỗi. Đưa code qua cổng đó lên một địa chỉ thật, và quay lại bản cũ khi cần, là việc của các bài viết sau.
Nếu bạn muốn đọc thêm cách khóa quyền ở database mà các test của form này đang dựa vào, hãy xem Row Level Security trong Supabase. Các câu hỏi về kiểm thử và CI nằm trong ngân hàng câu hỏi phỏng vấn. Tài liệu về npm ci nằm ở trang npm ci của npm.