Actions Keyword

Giới thiệu

Trong framework kiểm thử tự động, Actions là các từ khóa (keywords) được định nghĩa sẵn, đại diện cho các thao tác cụ thể mà hệ thống sẽ thực hiện trên trình duyệt (ví dụ: click, nhập dữ liệu, điều hướng trang, kiểm tra phần tử...).

Các Action này được sử dụng tại cột Action trong sheet Steps của file Excel testcase. Bằng cách kết hợp Action với Locator (để xác định phần tử trên giao diện) và Value (dữ liệu đầu vào hoặc giá trị mong muốn), bạn có thể mô phỏng lại hoàn chỉnh các bước thao tác của người dùng cuối.

Action keyword thường dùng

Dưới đây là danh sách các action có trong ATFramework được nhóm theo từng nhóm hành động cụ thể.

goto(value): Mở URL. Value = URL. Có thể dùng biến có sẵn
gotoMenu(value): Click menu liên tiếp. Value = menu items ngăn dấu phẩy

TC_ID	Step_No	Description	Action	Locator	Value
CHON	1	Vào trang menu	goto		${MENU}
CHON	2	Chọn menu và mở popup hợp đồng	gotoMenu		Hợp đồng gốc,Bảo hiểm xe cơ giới,Hợp đồng

Input (Nhập liệu)

fill(locator, value): Điền giá trị input. Locator = selector của input, Value = giá trị.
fillData(value): Điền toàn bộ các trường từ DataSheet. Value = "SHEET_NAME.rowId" (ví dụ: NNTT_DATA.row1)
fillGrid(locator, value): Điền toàn bộ các trường từ DataSheet. Locator = id của <table> lưới dữ liệu đó, Value = "SHEET_NAME". Nếu value bao gồm 2 sheet dạng SheetFill,SheetCheck thì SheetFill sẽ dùng để điền trên lưới còn SheetCheck sẽ dùng để kiểm tra giá trị trên lưới.
- Locator: selector root của grid
- Value: tên DataSheet, có thể kèm field filter
- Format Value:
Format Mô tả
SHEET Assert tất cả fields
SHEET||fields:DataID1;DataID2;DataID3 Chỉ assert DataID1, DataID2, DataID3

Với value của những trường là select có thể chọn theo thứ tự bản ghi trong danh sách bằng cú pháp: fieldValue||nth:3 (hoặc fieldValue||index:3); ||nth:1 (chọn bản ghi đầu tiên khi không cần lọc text)
fillFullData: Điền tất cả các row từ DataSheet theo tuần tự. Mặc định tự động điền dữ liệu và nhấn nút "Nhập" cho từng dòng. Value = "SHEET_NAME" (ví dụ: NNTT_DATA)

Chú ý: Dùng cho các Danh mục hệ thống (Danh mục trong line)
selectdanhmuc(value) : Chọn danh mục từ danh sách có sẵn, sẽ select danh mục từ DataSheet. Value = "SHEET_NAME" (ví dụ: selectdoituong). Chú ý với Dataset của selectdanhmuc cần 2 cột MA và TEN

Format	Mô tả
`SHEET`	Assert tất cả fields
`SHEET\|\|fields:DataID1;DataID2;DataID3`	Chỉ assert DataID1, DataID2, DataID3

Interaction (Thao tác)

click(locator, value?): Click element. Có thể cần value để thực hiện một số thao tác nâng cao như ấn giữ phím bất kỳ khi click modifiers:Shift|Alt|Ctrl|cmd| hoặc buộc click dù element có thể bị ẩn force:true|false
clickInGrid(locator, value): Click vào dòng trong grid. Locator = selector root của grid. Hỗ trợ 2 chế độ:

Chế độ 1 — Đơn giản: Value = text cần tìm trong <td> đầu tiên của dòng

TC_ID Step_No Description Action Locator Value
CHON 3 Chọn dòng trên lưới clickInGrid #ctl00_ContentPlaceHolder1_GR_lke Phụ tùng A

Chế độ 2 — Nhiều cột: Value = các cặp cot=giá_trị phân tách bởi ||. Giúp xác định chính xác dòng khi 1 cột không đủ phân biệt.

TC_ID Step_No Description Action Locator Value
CHON 3 Chọn mã trên lưới clickInGrid #ctl00_ContentPlaceHolder1_GR_lke ten=${data.row1.Phụ tùng}||ma=${data.row1.Mã}

So sánh với cách cũ:
```
# Cũ — dùng CSS selector phức tạp:
click | #grid td[cot="ten"]:has-text("Phụ tùng") >> nth=0

# Mới — đơn giản (1 cột):
clickInGrid | #grid | Phụ tùng

# Mới — chính xác (nhiều cột):
clickInGrid | #grid | ten=Phụ tùng||ma=PT001
```
:::tip Gợi ý Dùng clickInGrid thay cho click với CSS selector phức tạp khi cần xác định dòng trên grid. Giúp testcase dễ đọc và chính xác hơn. :::
wait(value): Đợi thời gian (ms). Value = milliseconds
press(value): Nhấn phím. Value = key name (Enter, Escape, Tab...)
clear(locator): Xóa nội dung input
select(locator, value): Chọn option dropdown. Value = option value
check/uncheck(locator, value): Check/uncheck checkbox
upload: Upload file vào input[type=file]. Locator = selector input file, Value = đường dẫn file
- Hỗ trợ đường dẫn tuyệt đối (C:\\files\\doc.xls) và tương đối (./data/doc.xls)
- Đường dẫn tương đối resolve theo thứ tự: thư mục Excel → thư mục project

TC_ID	Step_No	Description	Action	Locator	Value
CHON	3	Chọn dòng trên lưới	clickInGrid	#ctl00_ContentPlaceHolder1_GR_lke	Phụ tùng A

TC_ID	Step_No	Description	Action	Locator	Value
CHON	3	Chọn mã trên lưới	clickInGrid	#ctl00_ContentPlaceHolder1_GR_lke	ten=${data.row1.Phụ tùng}\|\|ma=${data.row1.Mã}

Assertions (So sánh kiểm tra giá trị)

:::tip Hỗ trợ nhiều Locator||Value Tất cả các action expect* bên dưới đều hỗ trợ kiểm tra nhiều element cùng lúc bằng cách phân tách Locator và Value bởi dấu ||.

TC_ID	Step_No	Description	Action	Locator	Value
CHECK	1	Kiểm tra 1 element (như cũ)	expectValue	#txt_ma	ABC
CHECK	2	Kiểm tra 3 element cùng lúc	expectValue	#txt_ma\|\|#txt_ten\|\|#txt_sdt	ABC\|\|Tên SP\|\|0123
CHECK	3	Kiểm tra 2 element hiển thị	expectVisible	#btn_luu\|\|#btn_huy
:::

expectVisible(locator): Kiểm tra element hiển thị
expectHidden(locator): Kiểm tra element ẩn
expectText(locator, value): Kiểm tra element chứa text. Value = text cần tìm
expectValue(locator, value): Kiểm tra input value. Value = expected value
expectClass(locator, value): Kiểm tra CSS class. Value = class name
expectChecked(locator): Kiểm tra checkbox đã check
expectEnabled(locator): Kiểm tra button enabled
expectDisabled(locator): Kiểm tra button disabled
expectEditable(locator): Kiểm tra input có thể nhập
expectEmpty(locator): Kiểm tra input rỗng
expectFocused(locator): Kiểm tra element được focus vào
expectFocusedInGrid(locator, value): Kiểm tra bản ghi đang được focus trong grid. Locator = id bảng/grid. Hỗ trợ 2 chế độ:
- Đơn giản: Value = text bản ghi cần kiểm tra (ví dụ: Phụ tùng A)
- Nhiều cột: Value = các cặp cot=giá_trị phân tách bởi || (ví dụ: ten=Phụ tùng||ma=PT001)
expectNotInGrid(locator, value): Kiểm tra bản ghi KHÔNG tồn tại trong grid, hoặc grid trống. Locator = id bảng/grid. Hỗ trợ 3 chế độ:
- Grid trống: Value để trống → kiểm tra grid không có dữ liệu
- Đơn giản: Value = text bản ghi cần kiểm tra (ví dụ: Phụ tùng A)
- Nhiều cột: Value = các cặp cot=giá_trị phân tách bởi || (ví dụ: ten=Phụ tùng||ma=PT001)
expectAttribute(locator, value): Kiểm tra attribute. Value = "name" hoặc "name:value"
expectURL(value): Kiểm tra URL. Value = URL hoặc /regex/
expectHasRedColor(locator): Kiểm tra link hoặc nút có màu đỏ. Ví dụ: link thanh toán có màu đỏ
expectHasYellowColor(locator): Kiểm tra link hoặc nút có màu vàng. Ví dụ: link thanh toán có màu vàng
expectHasNoColor(locator) Kiểm tra link không đổi màu (có màu xanh)
expectAriaSnapshot (Locator bắt buộc; Value có thể là name:main.aria.yml||timeout:15000 hoặc YAML inline bắt đầu bằng - ...)
expectSnapshot (Value ví dụ: name:dashboard.png||fullPage:true||maxDiffPixels:10; nếu có Locator thì snapshot theo element; dùng cùng name với saveSnapshot để kiểm tra lại đúng file đã lưu)
- Có Locator: snapshot theo element.
- Không Locator: snapshot toàn trang.
- Value có thể là tên snapshot hoặc options: name:login.png||fullPage:true||maxDiffPixels:10
- Dùng đúng cùng name với saveSnapshot để so sánh lại ảnh đã lưu.

expectGridData(Locator,Value) Giúp kiểm tra các giá trị trên lưới. Giống khi dùng fillGrid mà sử dụng 2 sheet. Locator là id của lưới, Value = SheetData muốn kiểm tra

Locator: selector root của grid
Value: tên DataSheet, có thể kèm options
Format Value:

Format	Mô tả
`SHEET`	Fill tất cả fields
`SHEET\|\|fields:DataID1;DataID2`	Chỉ fill DataID1, DataID2
`SHEET_FILL, SHEET_ASSERT`	Fill tất cả, rồi assert tất cả từ sheet 2
`SHEET_IN\|\|fields:DataID1;DataIDF2,SHEET_ASSERT\|\|fields:DataID3;DataID4`	Fill DataID1,DataID2 rồi assert DataID3,DataID4

expectDialog(Value) lắng nghe dialog tiếp theo, assert message, rồi dismiss (hoặc accept). Tương tự như setAutoDialog hay handleDialog

Value	Hành vi
(rỗng)	Chỉ dismiss dialog
`Bạn có muốn lưu không?`	Assert message chứa text, rồi dismiss
`/Lưu./` hoặc `re:Lưu.`	Assert regex, rồi dismiss
`expected:text\|\|action:accept`	Assert rồi accept
`expected:text\|\|prompt:Nhập`	Assert rồi accept với prompt text

Multi-page/Popup (Thao tác với Tabs)

Vì lý do giảm thông tin cần nhập cho testcase, hiện tại chỉ giữ lại một số actions như waitForNewPageAfterClick, closePage

waitForPopup: Chờ popup mở.
waitForNewTab: Tương tự waitForPopup
waitForNewPageAfterClick(locator): Click và chờ page mới. Value = tên page (optional, tự sinh nếu rỗng)
switchPage: Chuyển sang page khác. Value = tên page
closePage: Đóng page. Value = tên page (optional, đóng page active nếu rỗng)
bringToFront: Đưa page lên foreground. Value = tên page

Data Capture (Lưu thông tin)

:::tip Hỗ trợ nhiều Locator||Value Tất cả các action save* bên dưới đều hỗ trợ lưu nhiều element cùng lúc bằng cách phân tách Locator và Value bởi dấu ||.

TC_ID	Step_No	Description	Action	Locator	Value
SAVE	1	Lưu 1 giá trị (như cũ)	saveText	#txt_ma	savedMa
SAVE	2	Lưu 3 giá trị cùng lúc	saveText	#txt_ma\|\|#txt_ten\|\|#txt_sdt	var1\|\|var2\|\|var3
:::

saveText(locator, value): Lưu text của element vào biến. Value = tên biến
saveTextContent(locator, value): Lưu textContent của element vào variable (bao gồm text ẩn).
saveAttribute(locator, value): Lưu attribute vào biến. Value = "attributeName:variableName"
saveValue(locator, value): Lưu value của input vào biến

Cột `SaveData` — Tự động lưu dữ liệu sau mỗi step

Thay vì dùng action saveText / saveValue riêng, bạn có thể thêm cột SaveData trong sheet Steps. Sau khi step thực thi xong, engine sẽ tự động detect loại element tại Locator và lưu dữ liệu vào biến:

input/select/textarea → lưu inputValue()
Các element khác (span, div, td...) → lưu innerText()

TC_ID	Step_No	Description	Action	Locator	Value	SaveData
NHAP	1	Điền mã	fill	#ctl00_ContentPlaceHolder1_txt_ma	ABC123	savedMa
NHAP	2	Click nút Nhập	click	button:Nhập
NHAP	3	Kiểm tra mã đã lưu	expectValue	#ctl00_ContentPlaceHolder1_txt_ma		savedMa2
NHAP	4	So sánh 2 giá trị	expectValue	#ctl00_ContentPlaceHolder1_txt_ma	`${savedMa}`

Hỗ trợ nhiều Locator||SaveData — lưu nhiều giá trị cùng lúc:

TC_ID	Step_No	Description	Action	Locator	Value	SaveData
NHAP	5	Lưu 3 giá trị	expectValue	#txt_ma\|\|#txt_ten\|\|#txt_sdt	ABC\|\|Tên\|\|0123	var1\|\|var2\|\|var3

:::tip Gợi ý Dùng cột SaveData giúp giảm số step cần viết — không cần thêm step saveText/saveValue riêng. Hỗ trợ || để lưu nhiều giá trị cùng lúc. :::

saveSnapshot (Locator optional; Value ví dụ: name:dashboard.png||fullPage:true; ảnh sẽ được lưu vào snapshot baseline của Playwright để expectSnapshot đọc lại cùng name)
- Locator có thể để trống để chụp toàn trang.
- Value là tên file hoặc options, ví dụ: name:login.png||fullPage:true.
- Ảnh sẽ được lưu vào snapshot baseline của Playwright để expectSnapshot so sánh lại được khi dùng cùng name.
savePersistentText: tương tự saveText nhưng dữ liệu được lưu lại để sử dụng cho test sau
savePersistentTextContent
savePersistentAttribute (Value format: attributeName:variableName)
savePersistentValue

Các action savePersistent* sẽ ghi biến vào file JSON riêng và tự nạp lại ở các testcase/run tiếp theo.

Dialog (Xử lý dialog)

handleDialog(value): Xử lý dialog kế tiếp. Value = accept/dismiss/error
setAutoDialog(value): Xử lý tất cả dialog trên page. Value = accept/dismiss/error/none

Dialog phải đăng ký trước khi sự kiện xảy ra: Ví dụ như Khi click nút nhập nếu có dialog lỗi thì sẽ bắn lỗi và dừng test. Thì sẽ cần Step handleDialog hoặc setAutoDialog trước Step click nút Nhập.

Hỗ trợ expected và prompt trong Value

handleDialog và setAutoDialog giờ parse Value theo format mở rộng:

Value	Hành vi
`accept`	Accept dialog (như cũ)
`dismiss`	Dismiss dialog (như cũ)
`accept\|\|expected:Bạn có muốn lưu?`	Assert message chứa text trước khi accept
`accept\|\|expected:/Lưu.*/`	Assert message match regex
`accept\|\|prompt:Giá trị nhập`	Accept với giá trị nhập vào prompt dialog
`accept\|\|expected:Tiêu đề\|\|prompt:Nhập`	Assert + accept với prompt

Giới thiệu​

Action keyword thường dùng​

Navigation (Chuyển hướng)​

Input (Nhập liệu)​

Interaction (Thao tác)​

Assertions (So sánh kiểm tra giá trị)​

Multi-page/Popup (Thao tác với Tabs)​

Data Capture (Lưu thông tin)​

Cột SaveData — Tự động lưu dữ liệu sau mỗi step​

Dialog (Xử lý dialog)​