create-bql

Scaffold "viết .feature (BDD) → sinh .bql (BrowserQL của Browserless) → chạy và chấm Pass/Fail/Blocked" vào một project có sẵn (hoặc thư mục mới), qua 1 lệnh. Kèm autocomplete + gạch đỏ khi sai, cho cả .bql lẫn .feature.

Dùng cho project có sẵn

Đứng trong thư mục project (đã có package.json hoặc chưa cũng được), chạy:

npx create-bql

Dùng để tạo thư mục mới

npx create-bql ten-du-an-moi

Nó làm gì

Thêm vào project các file cần thiết để VS Code tự autocomplete + gạch đỏ khi sai cú pháp .bql, và chạy được file .bql bằng CLI:

• .env.example, graphql.config.yml
• .vscode/settings.json, .vscode/extensions.json (merge vào file có sẵn nếu bạn đã có, không xoá cấu hình cũ của bạn)
• schema/expect.graphql, schema/browserql.graphql (placeholder, sinh thật bằng npm run schema)
• scripts/fetch-schema.mjs, scripts/run-bql.mjs
• bql/smoke-form.bql (file mẫu viết tay)
• Tầng BDD (mới ở 0.2.0): features/lien-he.feature, steps/*.bql + steps/locators.json, scripts/generate.mjs (feature → bql), scripts/bdd.mjs (compiler + runner + báo cáo), fixtures/*.json (bộ test offline cho chính bộ chấm điểm)
• BQL-SETUP.md (hướng dẫn dùng, sau khi scaffold xong đọc file này)
• package.json: nếu project đã có sẵn, chỉ thêm script schema/bql/gen/bdd/check và dependency dotenv/graphql nếu bạn chưa có sẵn tên đó — không đụng tới phần khác trong file của bạn.

Nguyên tắc an toàn: file nào ở đích đã tồn tại thì được bỏ qua, không ghi đè. Riêng package.json, .vscode/settings.json, .vscode/extensions.json, .gitignore được merge (chỉ thêm phần thiếu). Chạy xong, terminal sẽ in rõ file nào được tạo mới / merge / bỏ qua.

Sau khi scaffold

Đọc file BQL-SETUP.md vừa được tạo trong project của bạn — đó là hướng dẫn đầy đủ từng bước (điền .env, sinh schema, viết .bql, chạy .bql, và mục 6: tầng BDD).

Tầng BDD làm gì

features/dang-nhap.feature     Gherkin — BA/khách đọc và ký được
steps/*.bql                    thư viện step: 1 step = 1 mảnh BQL thật
steps/locators.json            nhãn ô -> CSS selector
      ↓ npm run gen
bql/dang-nhap.bql              artifact review được, mỗi Scenario 1 mutation
      ↓ npm run bdd bql/dang-nhap.bql
  Scenario: Đăng nhập thành công
    Given tôi mở trang đăng nhập .............................. OK
    When tôi nhập "admin" vào ô "Tài khoản" ................... OK
    Then tôi thấy "Trang chủ" ở "Tiêu đề trang" ............... PASS

Không cần tầng step-definitions + page-object của Cucumber: thân step chính là BQL, selector nằm trong locators.json. @expect(...) trong .bql được compiler gỡ ra thành bảng chấm điểm trước khi gửi query lên server.

Mỗi Scenario chạy 1 request riêng = 1 phiên trình duyệt sạch. Báo cáo tách Blocked (server lỗi, selector không xuất hiện) khỏi Fail (assertion sai).