·

Quy trình Thực tế: Bộ Test Hồi quy API: Từ Spec đến CI

Đi qua một quy trình thực tế dùng Postman MCP để AI agent chạy và quản lý API collection, test suite từ đầu đến cuối.

Đây là bài tổng hợp, ráp lại toàn bộ kiến thức từ các bài trước thành một workflow hoàn chỉnh mà bạn có thể áp dụng ngay cho một service thật: từ OpenAPI spec ban đầu, qua AI sinh collection và assertion baseline, mở rộng độ phủ cho các case lỗi/auth/edge case, đến việc đưa collection run vào CI như một regression gate (cổng chặn regression) thực sự có quyền fail build - không chỉ là "test cho có". Nếu bạn chỉ đọc một bài trong module này để mang về áp dụng cho team, nên là bài này.

Tổng Quan Workflow: Từ OpenAPI Spec Đến Regression Gate Tự Động

Toàn bộ pipeline gồm 4 giai đoạn nối tiếp:

  1. Nguồn sự thật (source of truth): OpenAPI spec được maintain trong repo, mọi thay đổi API phải đi qua PR sửa spec trước.
  2. Sinh baseline: AI đọc spec, dựng collection Postman với request + assertion baseline (happy path, đúng schema).
  3. Mở rộng độ phủ: AI bổ sung test cho các case lỗi, xác thực, và edge case mà spec mô tả (hoặc suy ra từ business logic thực tế trong code).
  4. Gate trong CI: mỗi lần có PR hoặc deploy, collection được chạy tự động qua Postman CLI/Newman, kết quả quyết định pass/fail của pipeline; khi fail, AI hỗ trợ triage (phân loại) nguyên nhân trước khi người phụ trách phải tự đọc log.
openapi.yaml (git) --AI đọc--> Postman Collection (baseline)
                                        |
                          AI mở rộng edge case/auth/error
                                        |
                              CI: postman collection run
                                        |
                         Pass -> merge/deploy | Fail -> AI triage -> báo cáo

Điểm mấu chốt của workflow này: spec luôn là nguồn sự thật, AI không tự "sáng tác" business rule ngoài spec, và CI là nơi enforce (áp đặt) chứ không phải chỉ chạy tay khi nhớ ra.

Mẹo: Trước khi bắt đầu dựng workflow này cho một service có sẵn nhưng chưa có spec chuẩn, việc đầu tiên nên làm là để AI đọc code hiện tại và sinh ra OpenAPI spec khớp với thực tế - đừng để AI vừa đoán spec vừa sinh test cùng lúc, dễ dẫn đến test đúng theo cách hiểu sai của AI.

Bước 1: Sinh Collection, Environment và Assertion Baseline

Với spec đã có (hoặc vừa được chuẩn hóa ở bước trên), yêu cầu AI dựng bộ khung ban đầu:

Đọc docs/openapi.yaml. Tạo collection "Orders API - Regression" trong
workspace "AI Sandbox", tạo 2 environment "staging" và "ci" với biến
base_url tương ứng. Với mỗi endpoint, tạo 1 request happy path với
assertion: đúng status code khai báo trong spec, đúng schema response
(dùng pm.response.to.have.jsonSchema), thời gian phản hồi dưới 1000ms.

Kết quả: một collection có cấu trúc rõ ràng theo tag, mỗi request có assertion baseline nhất quán. Export ngay để review dưới dạng git diff trước khi đi tiếp:

postman collection export "orders-api-regression-id" \
  --output ./postman/orders-api-regression.postman_collection.json
git add ./postman/orders-api-regression.postman_collection.json
git diff --stat

Việc commit file JSON collection vào git ngay từ giai đoạn baseline giúp toàn bộ thay đổi sau này (do AI hay do người) đều có lịch sử rõ ràng, review được như review code thật.

Mẹo: Tạo file .postman/schema-cache/ lưu lại từng schema JSON được dùng trong assertion dưới dạng file riêng, import lại bằng biến thay vì lặp lại schema y hệt trong nhiều request - giảm rủi ro một request bị sửa schema mà quên sửa request khác dùng chung entity.

Bước 2: Mở Rộng Độ Phủ Cho Case Lỗi, Auth và Edge Case

Baseline mới chỉ cover happy path. Bước quan trọng nhất để có một bộ regression thật sự đáng tin là mở rộng cho các nhánh lỗi - đây cũng là nơi AI phát huy giá trị rõ nhất vì con người thường lười viết negative test đầy đủ.

Với mỗi endpoint trong collection "Orders API - Regression", bổ sung thêm
các request negative case sau (nếu áp dụng được theo spec):
- Thiếu Authorization header -> mong đợi 401
- Token hợp lệ nhưng thiếu quyền (role không đủ) -> mong đợi 403
- Request body thiếu field required -> mong đợi 400 với message rõ field nào thiếu
- Resource id không tồn tại -> mong đợi 404
- Request body có field đúng type nhưng giá trị vượt giới hạn nghiệp vụ
  (ví dụ quantity âm, quantity = 0) -> mong đợi 400
Đặt tên request theo format: "{METHOD} {path} - {tên case ngắn}".

Ví dụ assertion cho case thiếu quyền:

pm.test("Status is 403 when role lacks permission", () => {
    pm.response.to.have.status(403);
});

pm.test("Error response has clear message", () => {
    const body = pm.response.json();
    pm.expect(body).to.have.property("message");
    pm.expect(body.message.toLowerCase()).to.include("permission");
});

Với case liên quan auth, cần một environment riêng chứa các token đã chuẩn bị sẵn theo từng role (admin, member không đủ quyền, không có token) - quản lý qua Postman Vault như đã đề cập ở bài giới thiệu Postman MCP:

postman vault set TOKEN_ADMIN --value "eyJhbGciOi..."
postman vault set TOKEN_MEMBER_NO_PERMISSION --value "eyJhbGciOi..."

Mẹo: Yêu cầu AI liệt kê danh sách case nó SẼ tạo dưới dạng bảng trước khi tạo request thật - đây là lúc bạn phát hiện case bị AI hiểu sai nghiệp vụ (ví dụ nhầm quy tắc phân quyền) mà sửa ngay trên bảng kế hoạch, rẻ hơn nhiều so với sửa sau khi đã có 30 request sai.

Bước 3: Nối Collection Run Vào CI và Triage Lỗi Bằng AI

Giai đoạn biến bộ test từ "có tồn tại" thành "có tác dụng thật" là gắn nó vào CI với quyền fail pipeline. Ví dụ với GitHub Actions:

name: API Regression Suite
on:
  pull_request:
    paths: ["src/**", "docs/openapi.yaml"]

jobs:
  postman-regression:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install Postman CLI
        run: curl -o- "https://dl-cli.pstmn.io/install/linux64.sh" | sh
      - name: Login Postman CLI
        run: postman login --with-api-key "${{ secrets.POSTMAN_API_KEY }}"
      - name: Run regression collection
        run: |
          postman collection run "orders-api-regression-id" \
            --environment "ci-env-id" \
            --reporters cli,json,junit \
            --reporter-junit-export ./reports/junit.xml \
            --reporter-json-export ./reports/run-result.json
      - name: Publish test report
        uses: dorny/test-reporter@v1
        if: always()
        with:
          name: Postman Regression Results
          path: reports/junit.xml
          reporter: java-junit

Điểm quan trọng: postman collection run trả exit code khác 0 khi có test fail, nên bước CI này tự động fail cả pipeline - không cần thêm logic kiểm tra riêng. Khi có fail, thay vì để engineer đọc raw JSON dài, cho AI triage trước:

Đọc file reports/run-result.json từ lần chạy CI vừa fail. Tổng hợp:
1. Có bao nhiêu request fail, phân theo nhóm (auth/validation/business logic/network)
2. Với mỗi fail, chỉ ra assertion nào sai và giá trị thực tế nhận được
3. Đánh giá mức độ nghiêm trọng: có phải breaking change ảnh hưởng client
   hiện tại, hay chỉ là edge case hiếm gặp
Xuất kết quả dạng comment ngắn để dán vào PR.

Kết quả AI tổng hợp có thể dùng ngay làm comment PR:

## Kết quả Regression Suite - 3 test fail

**Nhóm validation (2 fail)**
- POST /orders - "quantity = 0 should fail": nhận 201 thay vì 400
  => Backend hiện tại chưa validate quantity > 0, cần fix ở
     OrderValidator trước khi merge.

**Nhóm business logic (1 fail)**
- PATCH /orders/{id}/status - "cancel completed order should fail":
  nhận 200 thay vì 409 => cho phép cancel order đã hoàn thành,
  có thể là bug nghiêm trọng ảnh hưởng dữ liệu tài chính, cần
  block merge cho tới khi fix.

Đề xuất: KHÔNG merge PR này, 2 vấn đề trên đều là bug thật ở code,
không phải lỗi test.

Mẹo: Để AI tự động dán báo cáo này thành comment trên PR qua GitHub CLI (gh pr comment) ngay trong bước CI khi fail - việc này biến quy trình từ "phải vào tab Actions xem log" thành "thấy ngay trong PR", giảm đáng kể thời gian phản hồi của reviewer.

Tips Thực Chiến Khi Vận Hành Regression Suite Lâu Dài

Sau khi workflow đã chạy ổn định vài tháng, đây là những kinh nghiệm giúp bộ regression không "mục nát" theo thời gian:

  • Gắn quyền sở hữu (ownership) rõ ràng cho collection: mỗi module/service nên có một người review chính chịu trách nhiệm duyệt các thay đổi do AI đề xuất trên collection của module đó, tránh tình trạng "ai cũng sửa được, không ai chịu trách nhiệm".
  • Theo dõi thời gian chạy suite: khi số request tăng lên hàng trăm, thời gian CI chạy regression có thể vượt vài phút - nên tách thành smoke (chạy mỗi PR) và full-regression (chạy theo lịch, ví dụ mỗi đêm hoặc trước release) để không làm chậm vòng lặp PR thông thường.
  • Định kỳ để AI rà soát assertion lỗi thời: mỗi khi spec đổi, yêu cầu AI quét toàn bộ collection tìm assertion tham chiếu field/schema cũ không còn tồn tại - đây là nguồn false positive (báo fail giả) phổ biến nhất của regression suite sống lâu.
  • Không để AI tự ý xóa test đang fail để "làm xanh" CI: luôn yêu cầu AI đề xuất fix hoặc đánh dấu skip kèm lý do rõ ràng trong PR riêng, không âm thầm xóa assertion đang phát hiện đúng bug.
jobs:
  smoke-on-pr:
    if: github.event_name == 'pull_request'
    # chạy folder "smoke" - vài chục request quan trọng nhất
  full-regression-nightly:
    if: github.event.schedule
    # chạy toàn bộ collection, báo cáo qua Slack/email

Mẹo: Thêm một dashboard nhỏ (có thể chỉ là một trang tổng hợp từ run-result.json lưu qua từng ngày) theo dõi xu hướng số lượng test fail/pass theo thời gian - xu hướng test fail tăng dần thường là dấu hiệu sớm của việc code đang lệch khỏi spec nhanh hơn tốc độ team cập nhật test.