Mở đầu — vì sao bài này quan trọng
Hãy tưởng tượng bạn vừa gia nhập đội QA của một sàn thương mại điện tử ở TP.HCM. Ngày đầu tiên, trưởng nhóm gửi cho bạn một file export Postman nặng 4 MB với hơn 300 request nằm phẳng lì trong một Collection duy nhất, tên đại loại như "Test API v2 final FINAL (copy)". Không có thư mục, không có mô tả, biến thì hard-code cả localhost:8080 lẫn api.staging.company.vn lẫn token của bạn dev cũ đã nghỉ việc từ ba tháng trước. Bạn mất trọn buổi sáng chỉ để tìm xem "request đăng nhập nằm ở đâu".
Đây không phải câu chuyện hiếm. Trong thực tế, phần lớn nỗi đau khi làm API testing bằng Postman không đến từ việc viết assertion khó, mà đến từ việc Collection bị tổ chức tệ. Một Collection lộn xộn giống như một tủ hồ sơ đổ hết giấy tờ vào chung một ngăn: về mặt lý thuyết mọi thứ đều "có đó", nhưng thực tế không ai dùng được, không ai bảo trì được, và không ai dám xóa cái gì vì sợ hỏng.
Bài này tập trung đúng vào một câu hỏi: làm sao tổ chức Collection cho gọn gàng, dễ chạy, dễ chia sẻ và dễ mở rộng theo thời gian. Chúng ta sẽ không đi sâu vào cách viết biến (bài 6), cách dùng environment (bài 5), hay cách viết pre-request/test script (bài 7, 8) — những phần đó có bài riêng. Ở đây, trọng tâm là kiến trúc cây thư mục, quy ước đặt tên, tài liệu hóa, và những best practice giúp Collection sống khỏe qua nhiều tháng.
Khái niệm cốt lõi
Collection là gì và vị trí của nó
Trong Postman, Collection là đơn vị tổ chức cao nhất — nó là "cây" gom nhóm các request lại với nhau. Bên dưới Collection, bạn có thể tạo Folder (thư mục), và Folder có thể lồng nhiều cấp. Mỗi request nằm trong một Folder hoặc nằm thẳng ở gốc Collection.
Điều quan trọng cần nhớ: Collection không chỉ là một cái túi đựng request. Nó mang theo nhiều thứ được kế thừa xuống các cấp con:
- Authorization cấu hình ở cấp Collection sẽ được request con kế thừa (trừ khi request tự ghi đè).
- Pre-request script và Test script ở cấp Collection/Folder chạy trước hoặc sau mỗi request nằm bên trong — đây là cơ chế để đặt logic dùng chung.
- Variables khai báo ở cấp Collection có phạm vi (scope) áp dụng cho toàn bộ request bên trong.
Ba triết lý nhóm request
Có ba cách phổ biến để nhóm request thành Folder, mỗi cách phục vụ một mục đích khác nhau:
1. Nhóm theo resource / endpoint (kiểu REST): Mỗi Folder ứng với một tài nguyên như Users, Products, Orders, Payments. Bên trong Users có Create User, Get User, Update User, Delete User. Cách này ánh xạ gần như 1-1 với tài liệu API, rất dễ tra cứu, phù hợp làm Collection tham chiếu (reference) cho cả team lẫn frontend dev.
2. Nhóm theo user journey / luồng nghiệp vụ: Folder tổ chức theo hành trình như 01 - Onboarding, 02 - Đặt hàng, 03 - Thanh toán, 04 - Hoàn tất đơn. Bên trong sắp theo thứ tự các bước cần chạy. Cách này lý tưởng cho Collection dùng để test end-to-end, nơi request sau phụ thuộc dữ liệu request trước.
3. Nhóm theo môi trường thử nghiệm / loại test: Smoke tests, Regression, Negative cases, Edge cases. Cách này giúp bạn chọn nhanh tập test cần chạy trong CI.
Sai lầm hay gặp là cố nhét cả ba triết lý vào một Collection. Kết quả là một cây thư mục vừa theo resource, vừa theo luồng, vừa theo loại test — không nhất quán và rối. Best practice: mỗi Collection chọn một triết lý chủ đạo. Nếu cần nhiều góc nhìn, hãy tách thành nhiều Collection (ví dụ một Collection "API Reference" theo resource và một Collection "E2E Flows" theo journey).
Cấu trúc đề xuất mẫu
Dưới đây là một khung cây tổ chức tốt cho một Collection test end-to-end của sàn thương mại điện tử:
Collection: Shopee-VN API Test Suite
│
├── 00 - Setup & Auth
│ ├── Health check
│ ├── Login (lưu token)
│ └── Refresh token
│
├── 01 - Product Catalog
│ ├── List products (pagination)
│ ├── Get product detail
│ └── Search products
│
├── 02 - Cart
│ ├── Add to cart
│ ├── Update quantity
│ └── Remove item
│
├── 03 - Checkout & Payment
│ ├── Create order
│ ├── Apply voucher
│ └── Confirm payment
│
├── 04 - Post-order
│ ├── Get order status
│ └── Cancel order
│
└── _teardown
└── Clean up test data
Vài quy ước đáng chú ý trong khung này: dùng tiền tố số (00, 01, 02) để ép thứ tự chạy và thứ tự hiển thị; tách riêng Folder 00 - Setup để đặt bước đăng nhập chung; và dùng dấu gạch dưới _teardown để đẩy folder dọn dẹp xuống cuối cùng khi sắp xếp theo bảng chữ cái.
Quy ước đặt tên
Tên request nên mô tả hành động và kết quả kỳ vọng, không phải chỉ ghi method + URL. So sánh:
- Kém:
POST /orders - Tốt:
Create order — happy path (200) - Tốt:
Create order — thiếu địa chỉ giao hàng (400)
Tình huống thực tế
Tình huống 1 — Sàn TMĐT gộp tất cả vào một Collection
Một startup TMĐT ở Hà Nội có đội QA 4 người dùng chung một Collection tên "Main API". Sau 8 tháng, Collection phình lên 420 request, không thư mục, biến baseUrl bị hard-code ở 60 request khác nhau. Khi công ty đổi domain staging từ staging.abc.vn sang stg.abc.io, một bạn QA phải sửa tay từng request, sót mất 7 cái, khiến CI đỏ suốt hai ngày mà không ai biết nguyên nhân.
Diễn giải: Vấn đề gốc không phải "quá nhiều request" mà là thiếu cấu trúc và thiếu biến ở cấp Collection. Nếu baseUrl được khai báo một lần ở Collection variable và mọi request tham chiếu {{baseUrl}}, việc đổi domain chỉ mất 30 giây.
Bài học: Ngay cả khi Collection còn nhỏ, hãy dựng khung Folder và đưa các giá trị dùng chung lên cấp Collection từ đầu. "Refactor sau" gần như không bao giờ xảy ra.
Tình huống 2 — Ngân hàng số tách Collection theo vòng đời
Một ví điện tử tại TP.HCM (giả định tên MoPay) tổ chức lại toàn bộ test theo ba Collection tách biệt: MoPay — Smoke (12 request) chạy mỗi lần deploy, MoPay — Regression (180 request) chạy hằng đêm, và MoPay — API Reference để dev tra cứu. Mỗi Collection có triết lý riêng: Smoke theo luồng critical, Regression theo resource, Reference theo resource kèm mô tả chi tiết.
Kết quả: pipeline deploy chỉ chạy 12 request Smoke trong 40 giây thay vì đợi 180 request. Khi cần điều tra bug, QA mở đúng Collection Regression. Frontend dev không bao giờ phải lội qua các ca negative test — họ có Collection Reference riêng.
Diễn giải: Việc tách theo mục đích sử dụng cho phép mỗi bên dùng đúng công cụ mình cần, và cho phép CI chạy nhanh tập nhỏ.
Bài học: Đừng ngại có nhiều Collection. Một Collection khổng lồ "làm mọi thứ" luôn thua ba Collection nhỏ có mục đích rõ ràng.
Tình huống 3 — Onboard nhân sự mới nhờ tài liệu hóa
Một công ty gia công phần mềm ở Đà Nẵng nhận một nhân viên QA mới. Trưởng nhóm giao đúng một link Collection. Nhờ mỗi Folder đều có phần Description viết bằng Markdown giải thích luồng nghiệp vụ, mỗi request đều có mô tả tham số và ví dụ response, và gốc Collection có một đoạn "Cách bắt đầu" (import environment nào, chạy Folder nào trước), bạn nhân viên mới tự chạy được toàn bộ suite trong buổi chiều đầu tiên mà không cần hỏi ai.
Diễn giải: Postman cho phép viết mô tả Markdown ở cấp Collection, Folder và request. Phần lớn team bỏ trống các ô này — và đó là lý do onboarding luôn tốn thời gian.
Bài học: Description không phải trang trí. Nó là tài liệu sống đi kèm ngay trong Collection, luôn cập nhật cùng test.
Hướng dẫn từng bước
Giả sử bạn đang xây một Collection test cho API đơn hàng của một sàn TMĐT. Làm theo trình tự sau:
- Tạo Collection và đặt tên có ý nghĩa. Ví dụ
TMĐT-VN — Order API E2E. Tránh tên chung chung như "Test" hay "New Collection".
- Viết mô tả gốc Collection. Ở tab Description, ghi rõ: Collection này test cái gì, cần import environment nào, thứ tự chạy Folder, và ai là người phụ trách. Đây là màn hình đầu tiên người khác thấy.
- Dựng khung Folder trước khi tạo request. Tạo
00 - Setup & Auth,01 - ...,02 - ...,_teardown. Việc dựng khung trước ép bạn suy nghĩ về kiến trúc thay vì vứt request bừa bãi.
- Đưa cấu hình dùng chung lên cấp Collection. Vào Collection → Variables, tạo
baseUrl. Vào Authorization cấp Collection, cấu hình kiểu xác thực chung để request con kế thừa (chi tiết auth ở bài 12).
- Tạo request vào đúng Folder, đặt tên mô tả rõ ràng. Theo mẫu
Hành động — ngữ cảnh (mã trạng thái kỳ vọng).
- Viết Description cho từng request quan trọng. Ghi rõ tham số bắt buộc, ví dụ body, và điều kiện tiên quyết (ví dụ "cần chạy Login trước").
- Sắp xếp thứ tự request trong Folder cho khớp luồng chạy. Postman chạy request trong Collection Runner theo đúng thứ tự bạn kéo-thả. Với Collection E2E, thứ tự này rất quan trọng.
- Chạy thử bằng Collection Runner để xác nhận toàn bộ cây chạy trơn tru theo thứ tự, trước khi chia sẻ hay đưa vào CI.
- Đưa Collection vào Workspace nhóm và version control. Lưu vào shared workspace để cả team cùng chỉnh, thay vì gửi file export qua chat (xem thêm bài 31 về collaboration).
Lỗi thường gặp & mẹo
Lỗi: Collection phẳng, không Folder. Khi vượt 20–30 request, không có thư mục là bạn đã mất kiểm soát. Mẹo: dựng Folder ngay từ khi có 5 request đầu tiên.
Lỗi: Trộn nhiều triết lý nhóm trong một Collection. Vừa theo resource vừa theo journey khiến người mới không biết tìm ở đâu. Mẹo: mỗi Collection một triết lý chủ đạo; cần nhiều góc nhìn thì tách Collection.
Lỗi: Hard-code URL và giá trị lặp lại trong từng request. Mẹo: mọi thứ dùng chung (baseUrl, version, timeout) đưa lên Collection variable và tham chiếu bằng {{...}}.
Lỗi: Tên request vô nghĩa như "test 1", "copy of Get". Báo cáo CI trở nên vô dụng. Mẹo: áp dụng quy ước đặt tên nhất quán và soát lại tên trước khi commit.
Lỗi: Không có Folder Setup/Teardown. Bước đăng nhập bị copy vào nhiều nơi, dữ liệu test rác tích tụ. Mẹo: luôn có 00 - Setup cho auth chung và _teardown để dọn dẹp.
Lỗi: Description trống trơn. Onboarding chậm, kiến thức nằm trong đầu một người. Mẹo: coi Description là bắt buộc cho Collection và mỗi Folder.
Mẹo bonus — dùng tiền tố số để ép thứ tự. Postman sắp Folder theo bảng chữ cái khi hiển thị; 00, 01, 02 giữ đúng trình tự nghiệp vụ. Dùng _ đầu tên (như _teardown) để đẩy xuống cuối.
Mẹo bonus — chia nhỏ để chạy chọn lọc. Nhóm test theo Folder giúp bạn chạy riêng từng Folder trong Collection Runner hoặc Newman, thay vì buộc phải chạy cả suite.
Bài tập thực hành
- Refactor một Collection phẳng. Lấy (hoặc tự tạo) một Collection có ít nhất 15 request nằm phẳng. Nhóm chúng thành tối thiểu 4 Folder theo triết lý resource. Đặt lại tên mọi request theo quy ước
Hành động — ngữ cảnh (mã trạng thái).
- Dựng khung E2E cho luồng đặt hàng. Tạo Collection mới
Đặt hàng TMĐT — E2Evới các Folder00 - Setup & Auth,01 - Giỏ hàng,02 - Thanh toán,03 - Sau đơn,_teardown. Tạo ít nhất 2 request trong mỗi Folder (dùng URL giả hoặc API công khai nhưreqres.in/jsonplaceholder.typicode.com). Sắp thứ tự request khớp luồng.
- Viết tài liệu. Cho Collection ở bài 2, viết Description gốc Collection giải thích cách bắt đầu, và Description cho từng Folder mô tả luồng nghiệp vụ của nó.
- Đưa cấu hình lên Collection. Tạo biến
baseUrlở cấp Collection và thay mọi URL hard-code trong request bằng{{baseUrl}}. Xác nhận đổi một chỗ là toàn bộ request đổi theo.
- Chạy và tự đánh giá. Mở Collection Runner, chạy toàn bộ cây theo thứ tự. Quan sát báo cáo và kiểm tra: tên request có đủ rõ để hiểu ca nào chạy gì không? Nếu chưa, sửa lại.
Tóm tắt
Collection là đơn vị tổ chức cao nhất trong Postman, và cách bạn tổ chức nó quyết định phần lớn việc suite test của bạn có dễ dùng, dễ bảo trì và dễ chia sẻ hay không. Ba ý cốt lõi cần nhớ:
- Chọn một triết lý nhóm rõ ràng cho mỗi Collection — theo resource, theo user journey, hoặc theo loại test — và đừng trộn lẫn. Cần nhiều góc nhìn thì tách thành nhiều Collection có mục đích riêng.
- Đưa mọi thứ dùng chung lên cấp Collection (biến, authorization, script setup) và tận dụng cơ chế kế thừa. Dùng Folder
00 - Setupcho bước chung và_teardownđể dọn dẹp, kèm quy ước đặt tên và tiền tố số để giữ trật tự. - Tài liệu hóa bằng Description ở cấp Collection và Folder — đây là tài liệu sống giúp onboard nhanh và giữ kiến thức không phụ thuộc một cá nhân.