@sun-asterisk/sungen 2.0.2 → 2.1.0

package/docs/gherkin standards/gherkin-core-standard.vi.md

@@ -1,4 +1,4 @@
-# Tiêu Chuẩn Gherkin - Cốt Lõi (Phiên Bản Cuối)
+# Tiêu Chuẩn Gherkin - Cốt Lõi v2
 
 **Áp dụng cho: Kiểm thử thủ công & Kiểm thử tự động**
 
@@ -23,7 +23,7 @@ Scenario: <Ai> <Làm gì> <Để đạt kết quả gì>
 ### Ví dụ
 ```gherkin
 Scenario: User logs in successfully with valid credentials
-  Given User open [Login] page
+  Given User is on [Login] page
   When User fill [Email] field with {{valid_email}}
   And User fill [Password] field with {{valid_password}}
   And User click [Submit] button
@@ -36,13 +36,36 @@ Scenario: User logs in successfully with valid credentials
 
 ### Định dạng
 ```
-<Actor> <Action> [<Target>] with {{<Value>}}
+[Keyword] User <Action> [Target Name] <Target Type> <with {{Value}}> <is State>
 ```
 
+### 17 Mẫu Pattern
+
+| # | Mẫu | Ví dụ |
+|---|------|-------|
+| ① | Hành động đơn giản | `click [Submit] button` |
+| ② | Hành động với dữ liệu | `fill [Email] field with {{email}}` |
+| ③ | Xác nhận trạng thái | `see [Submit] button is disabled` |
+| ④ | Trạng thái với dữ liệu | `see [Panel] dialog with {{title}} is hidden` |
+| ⑤ | Hai đối tượng (kéo thả) | `drag [Card] to [Column]` |
+| ⑥ | Phím toàn cục | `press Enter key` |
+| ⑦ | Phím trên đối tượng | `press Enter on [Search] field` |
+| ⑧ | Chờ thời gian | `wait for 3 seconds` |
+| ⑨ | Chờ element | `wait for [Loader] spinner is hidden` |
+| ⑩ | Cuộn trang | `scroll to [Footer] section` |
+| ⑪ | Chuyển frame | `switch to [Payment] frame` |
+| ⑫ | Có (số lượng/thuộc tính) | `see [Avatar] image has {{src}}` |
+| ⑬ | Ô bảng theo chỉ số hàng | `see [Users] table row 1 [Name] cell {{name}}` |
+| ⑭ | Ô bảng theo bộ lọc hàng | `see [Users] table row {{filter}} [Status] cell {{status}}` |
+| ⑮ | Hành động trong hàng bảng | `click [Edit] button in [Users] table row {{filter}}` |
+| ⑯ | Điều hướng | `is on [Dashboard] page` / `navigate to [Settings] page` |
+| ⑰ | Xác nhận văn bản | `see [Title] heading contains {{text}}` |
+
 ### Quy tắc
 - ✅ `Actor` + `Action` là **bắt buộc**
-- ✅ `Target` là **bắt buộc** với hầu hết action (trừ `open` / `wait for`)
+- ✅ `Target` là **bắt buộc** với hầu hết action (trừ `wait for` timeout)
 - ✅ `with {{Value}}` chỉ dùng khi action cần dữ liệu
+- ✅ `is State` để xác nhận trạng thái element
 - ❌ Không viết tự do (free-text)
 - ❌ Không dùng từ đồng nghĩa
 
@@ -54,6 +77,7 @@ Scenario: User logs in successfully with valid credentials
 | Action | ✅ Luôn luôn | `click`, `fill`, `see` |
 | Target | ✅ Hầu hết | `[Login] button` |
 | Value | ⚠️ Khi cần | `{{valid_email}}` |
+| State | ⚠️ Khi cần | `is disabled` |
 
 ---
 
@@ -69,6 +93,7 @@ Scenario: User logs in successfully with valid credentials
 
 ### Ví dụ
 ```gherkin
+✅ User is on [Login] page
 ✅ User click [Submit] button
 ❌ System sends verification email
 ❌ Backend validates password
@@ -81,28 +106,44 @@ Scenario: User logs in successfully with valid credentials
 
 ## 4️⃣ Action (Hành động)
 
-### Các Action được phép (chỉ 6 loại)
+### Các Action được phép (20 loại)
 
 | Action | Trường hợp sử dụng | Ví dụ |
 |--------|----------|---------|
-| `open` | Điều hướng đến page/screen | `User open [Login] page` |
 | `click` | Click button/link/element | `User click [Submit] button` |
 | `fill` | Nhập text vào input field | `User fill [Email] field with {{email}}` |
-| `select` | Chọn option từ dropdown/radio | `User select [Country] dropdown with {{country}}` |
-| `wait for` | Đợi element/điều kiện | `User wait for [Loader] icon` |
-| `see` | Verify khả năng hiển thị element | `User see [Error] message` |
+| `select` | Chọn option từ dropdown | `User select [Country] dropdown with {{country}}` |
+| `check` | Đánh dấu checkbox | `User check [Remember me] checkbox` |
+| `uncheck` | Bỏ đánh dấu checkbox | `User uncheck [Newsletter] checkbox` |
+| `toggle` | Bật/tắt switch | `User toggle [Dark mode] switch` |
+| `upload` | Tải file lên | `User upload [Avatar] file with {{avatar_path}}` |
+| `hover` | Di chuột lên element | `User hover [Info] icon` |
+| `drag` | Kéo thả element | `User drag [Card] to [Column]` |
+| `clear` | Xóa nội dung input | `User clear [Search] field` |
+| `see` | Verify hiển thị / trạng thái | `User see [Error] message` |
+| `press` | Nhấn phím bàn phím | `User press Enter key` |
+| `expand` | Mở rộng element | `User expand [Details] row` |
+| `collapse` | Thu gọn element | `User collapse [Details] row` |
+| `double click` | Double click element | `User double click [Cell] cell` |
+| `scroll to` | Cuộn đến element | `User scroll to [Footer] section` |
+| `switch to` | Chuyển sang frame | `User switch to [Payment] frame` |
+| `wait for` | Đợi element/điều kiện | `User wait for [Loader] spinner` |
+| `is on` | Xác nhận đang ở trang | `User is on [Login] page` |
+| `navigate to` | Điều hướng đến trang | `User navigate to [Settings] page` |
+
+> **Ghi chú**: `is on` và `navigate to` đều dùng cho điều hướng. `is on` là dạng ưu tiên cho step `Given`.
 
 ### Quy tắc
 - ✅ Sử dụng **động từ chính xác** từ danh sách trên
-- ❌ Không dùng từ đồng nghĩa: `type`, `enter`, `input`, `press`, `check`, `verify`, `expect`, v.v.
+- ❌ Không dùng từ đồng nghĩa: `type`, `enter`, `input`, `verify`, `expect`, v.v.
 - ❌ Không dùng action kết hợp: `click and wait`, `fill and submit`
 
 ### Anti-patterns (Mẫu sai)
 ```gherkin
-❌ User types {{password}} into [Password] field
-❌ User presses [Enter] key
-❌ User checks [Terms] checkbox
-❌ User verifies [Success] message appears
+❌ User types {{password}} into [Password] field     → Dùng: User fill [Password] field with {{password}}
+❌ User presses [Enter] key                          → Dùng: User press Enter key
+❌ User checks [Terms] checkbox                      → Dùng: User check [Terms] checkbox
+❌ User verifies [Success] message appears            → Dùng: User see [Success] message
 ```
 
 ---
@@ -114,20 +155,76 @@ Scenario: User logs in successfully with valid credentials
 [name] <element type>
 ```
 
-### Các loại Element
+### Các loại Element (40+)
+
+#### Tương tác cơ bản
+
+| Loại Element | Khi nào dùng | Ví dụ |
+|--------------|-------------|---------|
+| `button` | Nút có thể click | `[Submit] button` |
+| `link` | Hyperlink | `[Forgot password] link` |
+| `field` | Text input | `[Email] field` |
+| `textarea` | Text area nhiều dòng | `[Message] textarea` |
+| `heading` | Tiêu đề (h1-h6) | `[Welcome] heading` |
+| `text` | Nội dung text | `[Price] text` |
+| `image` | Hình ảnh | `[Avatar] image` |
+| `icon` | Icon/hình ảnh nhỏ | `[Close] icon` |
+
+#### Form controls
 
 | Loại Element | Khi nào dùng | Ví dụ |
 |--------------|-------------|---------|
-| `field` | Text input, textarea | `[Email] field`, `[Password] field` |
-| `button` | Button có thể click | `[Submit] button`, `[Cancel] button` |
 | `checkbox` | Checkbox input | `[Remember me] checkbox` |
-| `dropdown` | Select element | `[Country] dropdown` |
 | `radio` | Radio button | `[Payment method] radio` |
-| `link` | Hyperlink | `[Forgot password] link` |
-| `message` | Alert/notification | `[Error] message`, `[Success] message` |
-| `page` | Toàn bộ màn hình/page | `[Login] page`, `[Dashboard] page` |
-| `icon` | Icon/hình ảnh hiển thị | `[Loader] icon`, `[Close] icon` |
-| `label` | Text label | `[Username] label` |
+| `switch` | Toggle switch | `[Dark mode] switch` |
+| `dropdown` | Select/combobox | `[Country] dropdown` |
+| `option` | Option trong dropdown | `[Vietnam] option` |
+| `slider` | Thanh trượt | `[Volume] slider` |
+| `uploader` | Vùng upload file | `[Document] uploader` |
+| `file` | File input | `[Avatar] file` |
+
+#### Overlay & navigation
+
+| Loại Element | Khi nào dùng | Ví dụ |
+|--------------|-------------|---------|
+| `dialog` | Hộp thoại | `[Confirm] dialog` |
+| `modal` | Modal overlay | `[Edit] modal` |
+| `menu` | Menu dropdown | `[Actions] menu` |
+| `menuitem` | Mục trong menu | `[Delete] menuitem` |
+| `tab` | Tab header | `[Settings] tab` |
+| `tabpanel` | Nội dung tab | `[General] tabpanel` |
+| `tooltip` | Tooltip | `[Help] tooltip` |
+| `alert` | Thông báo | `[Error] alert` |
+
+#### Cấu trúc & layout
+
+| Loại Element | Khi nào dùng | Ví dụ |
+|--------------|-------------|---------|
+| `list` | Danh sách | `[Results] list` |
+| `listitem` | Mục trong danh sách | `[Item 1] listitem` |
+| `table` | Bảng dữ liệu | `[Users] table` |
+| `row` | Hàng trong bảng | `[Row 1] row` |
+| `cell` | Ô trong bảng | `[Name] cell` |
+| `column` | Cột | `[Status] column` |
+| `columnheader` | Tiêu đề cột | `[Name] columnheader` |
+| `region` | Vùng landmark | `[Main] region` |
+| `section` | Section | `[Footer] section` |
+| `nav` | Thanh navigation | `[Main] nav` |
+| `banner` | Banner | `[Top] banner` |
+| `header` | Header | `[Page] header` |
+| `footer` | Footer | `[Page] footer` |
+
+#### Đặc biệt
+
+| Loại Element | Khi nào dùng | Ví dụ |
+|--------------|-------------|---------|
+| `page` | Toàn bộ trang | `[Login] page` |
+| `spinner` | Loading indicator | `[Loader] spinner` |
+| `progressbar` | Thanh tiến trình | `[Upload] progressbar` |
+| `tree` | Cấu trúc cây | `[Files] tree` |
+| `treeitem` | Mục trong cây | `[Folder] treeitem` |
+| `frame` | Iframe | `[Payment] frame` |
+| `iframe` | Iframe (tương đương frame) | `[Embed] iframe` |
 
 ### Quy tắc
 - ✅ Dùng **tên có nghĩa nghiệp vụ/UI**, không dùng selector kỹ thuật
@@ -140,8 +237,9 @@ Scenario: User logs in successfully with valid credentials
 ```gherkin
 ✅ User click [Login] button
 ✅ User fill [Email address] field with {{email}}
-✅ User select [United States] dropdown
-✅ User see [Welcome back] message
+✅ User check [Remember me] checkbox
+✅ User toggle [Dark mode] switch
+✅ User see [Welcome back] heading
 
 ❌ User click [#submit-btn] button
 ❌ User fill [input.email-field] field
@@ -192,7 +290,26 @@ expired_otp: "000000"
 ## 7️⃣ Assertion (Xác nhận)
 
 ### Động từ
-- **Chỉ dùng**: `see`
+- **Chính**: `see` (xác nhận hiển thị / trạng thái)
+
+### States (Trạng thái)
+
+Thêm `is <state>` vào cuối step `see` hoặc `wait for` để xác nhận trạng thái:
+
+| State | Mô tả | Ví dụ |
+|-------|--------|-------|
+| `hidden` | Element bị ẩn | `User see [Modal] dialog is hidden` |
+| `visible` | Element hiển thị | `User see [Banner] section is visible` |
+| `disabled` | Element bị vô hiệu | `User see [Submit] button is disabled` |
+| `enabled` | Element có thể tương tác | `User see [Submit] button is enabled` |
+| `checked` | Checkbox/radio được chọn | `User see [Terms] checkbox is checked` |
+| `unchecked` | Checkbox/radio chưa chọn | `User see [Terms] checkbox is unchecked` |
+| `focused` | Element đang được focus | `User see [Email] field is focused` |
+| `empty` | Element rỗng | `User see [Search] field is empty` |
+| `loading` | Element đang tải | `User see [Content] section is loading` |
+| `selected` | Element được chọn | `User see [Tab 1] tab is selected` |
+| `sorted ascending` | Sắp xếp tăng dần | `User see [Name] columnheader is sorted ascending` |
+| `sorted descending` | Sắp xếp giảm dần | `User see [Name] columnheader is sorted descending` |
 
 ### Quy tắc
 - ✅ Assertion **chỉ xuất hiện trong `Then`**
@@ -201,26 +318,101 @@ expired_otp: "000000"
 - ❌ Không mô tả hành động của user
 - ❌ Không dùng từ đồng nghĩa: `verify`, `expect`, `check`, `observe`, `validate`
 
+### Các mẫu Assertion
+
+| Mẫu | Trường hợp sử dụng | Ví dụ |
+|---------|----------|---------|
+| Hiển thị đơn giản | Element có thể nhìn thấy | `User see [Login] button` |
+| Hiển thị với giá trị | Element chứa text cụ thể | `User see [Welcome] heading with {{username}}` |
+| Xác nhận trạng thái | Element ở trạng thái nhất định | `User see [Submit] button is disabled` |
+| Trạng thái với giá trị | Element có giá trị và trạng thái | `User see [Panel] dialog with {{title}} is hidden` |
+| Chứa text | Element chứa text | `User see [Title] heading contains {{text}}` |
+| Có thuộc tính | Element có thuộc tính/giá trị | `User see [Avatar] image has {{src}}` |
+| Verify page | Xác nhận điều hướng | `User is on [Dashboard] page` |
+| Chờ ẩn | Đợi element biến mất | `User wait for [Loader] spinner is hidden` |
+
+### Xác nhận bảng (Table Assertions)
+
+| Mẫu | Ví dụ |
+|------|-------|
+| Ô theo chỉ số hàng | `User see [Users] table row 1 [Name] cell {{name}}` |
+| Ô theo bộ lọc hàng | `User see [Users] table row {{filter}} [Status] cell {{status}}` |
+| Hành động trong hàng | `User click [Edit] button in [Users] table row {{filter}}` |
+| Đếm số hàng | `User see [Users] table has {{count}} rows` |
+| Bảng rỗng | `User see [Users] table is empty` |
+| Có cột | `User see [Users] table has [Email] column` |
+
 ### Ví dụ
 ```gherkin
-✅ Then User see [Error] message
+✅ Then User see [Error] alert
 ✅ And User see [Dashboard] page
-✅ And User see [Welcome] text
-✅ And User see [Logout] button
+✅ And User see [Welcome] heading with {{username}}
+✅ And User see [Submit] button is disabled
+✅ And User see [Terms] checkbox is checked
+✅ And User see [Users] table row 1 [Name] cell {{name}}
 
 ❌ Then User verifies [Error] message
 ❌ Then System displays [Dashboard] page
 ❌ Then [Success] message appears
 ```
 
-### Các mẫu Assertion
+---
 
-| Mẫu | Trường hợp sử dụng | Ví dụ |
-|---------|----------|---------|
-| Hiển thị đơn giản | Element có thể nhìn thấy | `User see [Login] button` |
-| Hiển thị với giá trị | Element chứa text cụ thể | `User see [Welcome] text with {{username}}` |
-| Verify page/trạng thái | Xác nhận điều hướng | `User see [Dashboard] page` |
-| Verify message | Xác nhận phản hồi | `User see [Error] message` |
+## 🏷️ Tags
+
+### Scenario Tags
+
+| Tag | Mô tả |
+|-----|-------|
+| `@auth:<role>` | Sử dụng trạng thái auth Playwright cho role đã cho |
+| `@no-auth` | Tắt authentication kế thừa |
+| `@steps:<name>` | Đánh dấu scenario là khối step tái sử dụng |
+| `@extend:<name>` | Chèn step từ khối `@steps` trước step hiện tại |
+| `@manual` | Bỏ qua scenario khi sinh code |
+
+Tags có thể áp dụng ở **cấp Feature** (kế thừa cho tất cả scenario) hoặc **cấp Scenario** (ghi đè Feature).
+
+**Thứ tự ưu tiên Auth**: Scenario kế thừa `@auth` > Scenario gốc `@auth` > Feature `@auth`
+
+### Step tái sử dụng (@steps / @extend)
+
+Dùng `@steps:<name>` để định nghĩa khối tái sử dụng và `@extend:<name>` để kế thừa:
+
+```gherkin
+@auth:user @steps:open-dialog
+Scenario: Open kudos dialog
+  Given User is on [Kudo] page
+  When User click [Notifications] button
+  And User click [Write Kudos] menuitem
+  Then User see [Panel] dialog with {{kudo_title}}
+
+@auth:user @extend:open-dialog
+Scenario: User sends a thank you message
+  Given User is on [Panel] dialog with {{kudo_title}}
+  When User click [Search] button
+  And User fill [Search] field with {{teammate_name}}
+  And User click [Teammate] row with {{teammate_name}}
+  And User fill [Title] field with {{teammate_title}}
+  And User fill [Message] textarea with {{teammate_message}}
+  And User click [Hashtag] button with {{hashtag_1}}
+  And User click [Send] button
+  And User wait for [Panel] dialog with {{kudo_title}} is hidden
+  Then User see [Panel] modal with {{kudo_title}} is hidden
+```
+
+**Hành vi:**
+- Scenario `@steps` sinh test riêng VÀ đăng ký step để tái sử dụng
+- Scenario `@extend` nhận step gốc chèn vào đầu — test hoàn toàn độc lập
+- Nhiều scenario có thể extend cùng một khối `@steps`
+- Code sinh ra có comment phân đoạn: `// [from @steps:<name>]`
+
+### Annotation cấp Step (cú pháp comment)
+
+| Annotation | Hiệu lực |
+|-----------|--------|
+| `# @ignore` | Bỏ qua step này khi sinh code |
+| `# @ignore-testcase` | Bỏ qua toàn bộ scenario khi sinh code |
+| `# @skip-production` | Bỏ qua step trong môi trường production |
 
 ---
 
@@ -230,30 +422,47 @@ expired_otp: "000000"
 Feature: User Authentication
   Path: /auth/login
 
+  @auth:admin
   Scenario: User logs in successfully with valid credentials
-    Given User open [Login] page
+    Given User is on [Login] page
     When User fill [Email] field with {{valid_email}}
     And User fill [Password] field with {{valid_password}}
-    And User click [Remember me] checkbox
+    And User check [Remember me] checkbox
     And User click [Submit] button
     Then User see [Dashboard] page
-    And User see [Welcome] message with {{username}}
+    And User see [Welcome] heading with {{username}}
 
+  @no-auth
   Scenario: User fails to login with invalid credentials
-    Given User open [Login] page
+    Given User is on [Login] page
     When User fill [Email] field with {{invalid_email}}
     And User fill [Password] field with {{invalid_password}}
     And User click [Submit] button
-    Then User see [Error] message
+    Then User see [Error] alert
+    And User see [Submit] button is enabled
     And User see [Login] page
 
-  Scenario: User selects preferred language during registration
-    Given User open [Registration] page
+  @no-auth
+  Scenario: User registers with preferred language
+    Given User is on [Registration] page
     When User fill [Email] field with {{new_email}}
     And User fill [Password] field with {{new_password}}
     And User select [Language] dropdown with {{preferred_language}}
+    And User check [Terms] checkbox
     And User click [Sign up] button
     Then User see [Verification] page
+
+  Scenario: User manages settings with various controls
+    Given User is on [Settings] page
+    When User toggle [Dark mode] switch
+    And User select [Timezone] dropdown with {{timezone}}
+    And User upload [Avatar] file with {{avatar_path}}
+    And User press Enter key
+    And User scroll to [Save] section
+    And User click [Save] button
+    And User wait for [Loader] spinner is hidden
+    Then User see [Success] alert
+    And User see [Dark mode] switch is checked
 ```
 
 ---
@@ -261,10 +470,12 @@ Feature: User Authentication
 ## ✅ Tham Khảo Nhanh
 
 ### Nên làm ✅
-- Dùng **6 action chuẩn**: open, click, fill, select, wait for, see
+- Dùng **20 action chuẩn** từ danh sách action
 - Dùng **`User`** là actor duy nhất
 - Dùng định dạng **`[Target] <element type>`**
 - Dùng **`{{snake_case}}`** cho giá trị
+- Dùng **`is <state>`** cho xác nhận trạng thái
+- Dùng **tags** (`@auth`, `@steps`, `@extend`) để quản lý scenario
 - **1 Scenario = 1 flow nghiệp vụ**
 - **1 Step = 1 action hoặc assertion**
 
@@ -274,7 +485,7 @@ Feature: User Authentication
 - Không dùng selector kỹ thuật (CSS/XPath/ID)
 - Không hard-code dữ liệu trong step
 - Không dùng action kết hợp
-- Không dùng `verify`/`check`/`expect` (dùng `see`)
+- Không dùng `verify`/`check`/`expect` thay cho `see`
 
 ---
 
@@ -282,22 +493,21 @@ Feature: User Authentication
 
 | Lợi ích | Mô tả |
 |---------|-------------|
-| **Nhất quán** | Cùng một mẫu cho tất cả test case |
+| **Nhất quán** | Cùng 17 mẫu pattern cho tất cả test case |
 | **Dễ đọc** | Người không kỹ thuật cũng hiểu được |
 | **Dễ bảo trì** | Dễ cập nhật khi UI thay đổi |
-| **Sẵn sàng tự động** | Ánh xạ trực tiếp sang code pattern |
+| **Sẵn sàng tự động** | Ánh xạ trực tiếp sang Playwright code |
 | **Không mơ hồ** | Mỗi step chỉ có một cách hiểu |
-| **Hỗ trợ công cụ** | Tương thích với framework Sungen |
+| **Hỗ trợ công cụ** | Tương thích với framework Sungen v2 |
+| **Tái sử dụng** | `@steps` / `@extend` giúp tái sử dụng flow |
 
 ---
 
 ## 📚 Tài Liệu Liên Quan
-- [Hướng dẫn Selector Override](selector-override.md) - Tùy chỉnh selector element
-- [Hướng dẫn Validation](validate.md) - Validate file Gherkin
-- [Thiết lập Auth](makeauth.md) - Cấu hình trạng thái authentication
+- [Từ điển Gherkin](../gherkin-dictionary.md) — Ngữ pháp đầy đủ, 17 mẫu pattern, quy tắc compiler
 
 ---
 
-**Phiên bản**: 1.0  
-**Trạng thái**: Final  
-**Cập nhật lần cuối**: 11 tháng 2, 2026
+**Phiên bản**: 2.0
+**Trạng thái**: Final
+**Cập nhật lần cuối**: 19 tháng 3, 2026

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sun-asterisk/sungen",
-  "version": "2.0.2",
+  "version": "2.1.0",
   "description": "Deterministic E2E Test Compiler - Gherkin + Selectors → Playwright tests",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -25,7 +25,7 @@
     "automation",
     "qa"
   ],
-  "author": "Bach Ngoc Hoai",
+  "author": "ee team (engineer-excellence) — Sun Asterisk",
   "license": "MIT",
   "engines": {
     "node": ">=18.0.0"

package/src/cli/commands/init.ts

@@ -4,10 +4,11 @@ export function registerInitCommand(program: Command): void {
   program
     .command('init [projectName]')
     .description('Initialize Sungen project (optionally create and initialize in a new project folder)')
-    .action(async (projectName?: string) => {
+    .requiredOption('--base-url <url>', 'Base URL for Playwright tests (e.g. https://your-app.com)')
+    .action(async (projectName: string | undefined, options: { baseUrl: string }) => {
       try {
         const { ProjectInitializer } = require('../../orchestrator/project-initializer');
-        const initializer = new ProjectInitializer();
+        const initializer = new ProjectInitializer(options.baseUrl);
         await initializer.initialize(projectName);
       } catch (error) {
         console.error('❌ Init failed:', error);

package/src/cli/index.ts

@@ -16,7 +16,7 @@ async function main() {
   program
     .name('sungen')
     .description('Deterministic E2E Test Compiler — Gherkin + Selectors → Playwright')
-    .version('2.0.2');
+    .version('2.1.0');
 
   // Global options
   program

package/src/generators/test-generator/adapters/playwright/templates/steps/actions/unknown-element-action.hbs

@@ -1 +1 @@
-await page.getByText('{{escapeQuotes selectorValue}}').filter({ hasText: {{#if (eq selectorValue "")}}/.*{{escapeRegex dataValue}}$/{{else}}'{{escapeQuotes dataValue}}'{{/if}} }){{#if (gt nth 0)}}.nth({{subtract nth 1}}){{/if}}.{{action}}();
+await page.getByText('{{escapeQuotes selectorValue}}').filter({ hasText: {{#if (eq selectorValue "")}}/.*{{escapeRegex dataValue}}$/{{else}}'{{escapeQuotes dataValue}}'{{/if}} }){{#if (gte nth 0)}}.nth({{nth}}){{/if}}.{{action}}();

package/src/generators/test-generator/adapters/playwright/templates/steps/assertions/disabled-with-role-variable-assertion.hbs

@@ -1,6 +1,6 @@
 await page.waitForLoadState('networkidle');
 {{#if name}}
-await expect(page.getByRole('{{role}}', { name: '{{escapeQuotes name}}'{{#if exact}}, exact: true{{/if}} }).filter({ hasText: /^{{escapeRegex dataValue}}$/ }){{#if (gt nth 0)}}.nth({{subtract nth 1}}){{/if}}).toBeDisabled();
+await expect(page.getByRole('{{role}}', { name: '{{escapeQuotes name}}'{{#if exact}}, exact: true{{/if}} }).filter({ hasText: /^{{escapeRegex dataValue}}$/ }){{#if (gte nth 0)}}.nth({{nth}}){{/if}}).toBeDisabled();
 {{else}}
-await expect(page.getByRole('{{role}}'{{#if exact}}, { exact: true }{{/if}}).filter({ hasText: /^{{escapeRegex dataValue}}$/ }){{#if (gt nth 0)}}.nth({{subtract nth 1}}){{/if}}).toBeDisabled();
+await expect(page.getByRole('{{role}}'{{#if exact}}, { exact: true }{{/if}}).filter({ hasText: /^{{escapeRegex dataValue}}$/ }){{#if (gte nth 0)}}.nth({{nth}}){{/if}}).toBeDisabled();
 {{/if}}

package/src/generators/test-generator/adapters/playwright/templates/steps/assertions/disabled-with-variable-assertion.hbs

@@ -1,2 +1,2 @@
 await page.waitForLoadState('networkidle');
-await expect(page.getByText('{{escapeQuotes selectorRef}}').filter({ hasText: {{#if (eq selectorValue "")}}/.*{{escapeRegex dataValue}}$/{{else}}'{{escapeQuotes dataValue}}'{{/if}} }){{#if (gt nth 0)}}.nth({{subtract nth 1}}){{/if}}).toBeDisabled();
+await expect(page.getByText('{{escapeQuotes selectorRef}}').filter({ hasText: {{#if (eq selectorValue "")}}/.*{{escapeRegex dataValue}}$/{{else}}'{{escapeQuotes dataValue}}'{{/if}} }){{#if (gte nth 0)}}.nth({{nth}}){{/if}}).toBeDisabled();

package/src/generators/test-generator/adapters/playwright/templates/steps/assertions/hidden-with-role-variable-assertion.hbs

@@ -1,6 +1,6 @@
 await page.waitForLoadState('networkidle');
 {{#if name}}
-await expect(page.getByRole('{{role}}', { name: '{{escapeQuotes name}}'{{#if exact}}, exact: true{{/if}} }).filter({ hasText: /^{{escapeRegex dataValue}}$/ }){{#if (gt nth 0)}}.nth({{subtract nth 1}}){{/if}}).toBeHidden();
+await expect(page.getByRole('{{role}}', { name: '{{escapeQuotes name}}'{{#if exact}}, exact: true{{/if}} }).filter({ hasText: /^{{escapeRegex dataValue}}$/ }){{#if (gte nth 0)}}.nth({{nth}}){{/if}}).toBeHidden();
 {{else}}
-await expect(page.getByRole('{{role}}'{{#if exact}}, { exact: true }{{/if}}).filter({ hasText: /^{{escapeRegex dataValue}}$/ }){{#if (gt nth 0)}}.nth({{subtract nth 1}}){{/if}}).toBeHidden();
+await expect(page.getByRole('{{role}}'{{#if exact}}, { exact: true }{{/if}}).filter({ hasText: /^{{escapeRegex dataValue}}$/ }){{#if (gte nth 0)}}.nth({{nth}}){{/if}}).toBeHidden();
 {{/if}}

package/src/generators/test-generator/adapters/playwright/templates/steps/assertions/hidden-with-variable-assertion.hbs

@@ -1,2 +1,2 @@
 await page.waitForLoadState('networkidle');
-await expect(page.getByText('{{escapeQuotes selectorRef}}').filter({ hasText: {{#if (eq selectorValue "")}}/.*{{escapeRegex dataValue}}$/{{else}}'{{escapeQuotes dataValue}}'{{/if}} }){{#if (gt nth 0)}}.nth({{subtract nth 1}}){{/if}}).toBeHidden();
+await expect(page.getByText('{{escapeQuotes selectorRef}}').filter({ hasText: {{#if (eq selectorValue "")}}/.*{{escapeRegex dataValue}}$/{{else}}'{{escapeQuotes dataValue}}'{{/if}} }){{#if (gte nth 0)}}.nth({{nth}}){{/if}}).toBeHidden();

package/src/generators/test-generator/adapters/playwright/templates/steps/assertions/visible-with-role-variable-assertion.hbs

@@ -1,10 +1,10 @@
 await page.waitForLoadState('networkidle');
 {{#if name}}
 {{#if dataValue}}
-await expect(page.getByRole('{{role}}', { name: '{{escapeQuotes name}}'{{#if exact}}, exact: true{{/if}} }).filter({ hasText: /^{{escapeRegex dataValue}}$/ }){{#if (gt nth 0)}}.nth({{subtract nth 1}}){{/if}}).toBeVisible();
+await expect(page.getByRole('{{role}}', { name: '{{escapeQuotes name}}'{{#if exact}}, exact: true{{/if}} }).filter({ hasText: /^{{escapeRegex dataValue}}$/ }){{#if (gte nth 0)}}.nth({{nth}}){{/if}}).toBeVisible();
 {{else}}
-await expect(page.getByRole('{{role}}', { name: '{{escapeQuotes name}}'{{#if exact}}, exact: true{{/if}} }){{#if (gt nth 0)}}.nth({{subtract nth 1}}){{/if}}).toBeVisible();
+await expect(page.getByRole('{{role}}', { name: '{{escapeQuotes name}}'{{#if exact}}, exact: true{{/if}} }){{#if (gte nth 0)}}.nth({{nth}}){{/if}}).toBeVisible();
 {{/if}}
 {{else}}
-await expect(page.getByRole('{{role}}'{{#if exact}}, { exact: true }{{/if}}).filter({ hasText: /^{{escapeRegex dataValue}}$/ }){{#if (gt nth 0)}}.nth({{subtract nth 1}}){{/if}}).toBeVisible();
+await expect(page.getByRole('{{role}}'{{#if exact}}, { exact: true }{{/if}}).filter({ hasText: /^{{escapeRegex dataValue}}$/ }){{#if (gte nth 0)}}.nth({{nth}}){{/if}}).toBeVisible();
 {{/if}}

package/src/generators/test-generator/adapters/playwright/templates/steps/assertions/visible-with-value-assertion.hbs

@@ -1,2 +1,2 @@
 await page.waitForLoadState('networkidle');
-await expect(page.getByText('{{escapeQuotes value}}'{{#if exact}}, { exact: true }{{/if}}){{#if (gt nth 0)}}.nth({{subtract nth 1}}){{/if}}).toBeVisible();
+await expect(page.getByText('{{escapeQuotes value}}'{{#if exact}}, { exact: true }{{/if}}){{#if (gte nth 0)}}.nth({{nth}}){{/if}}).toBeVisible();

package/src/generators/test-generator/adapters/playwright/templates/steps/assertions/visible-with-variable-assertion.hbs

@@ -1,2 +1,2 @@
 await page.waitForLoadState('networkidle');
-await expect(page.getByText('{{escapeQuotes selectorValue}}').filter({ hasText: /.*{{escapeRegex dataValue}}$/ }){{#if (gt nth 0)}}.nth({{subtract nth 1}}){{/if}}).toBeVisible();
+await expect(page.getByText('{{escapeQuotes selectorValue}}').filter({ hasText: /.*{{escapeRegex dataValue}}$/ }){{#if (gte nth 0)}}.nth({{nth}}){{/if}}).toBeVisible();

package/src/generators/test-generator/adapters/playwright/templates/steps/partials/locator-nth.hbs

@@ -1 +1 @@
-{{#if (gt nth 0)}}.nth({{subtract nth 1}}){{/if}}
+{{#if (gte nth 0)}}.nth({{nth}}){{/if}}