csharp-selenium-test-gen

name: csharp-selenium-test-gen description: Hướng dẫn AI Agent tự động viết code C# NUnit Selenium Test (Data-Driven) sử dụng dữ liệu từ ExcelDumperTool và UI-Map YAML.

Hướng Dẫn Tự Động Viết Test C# NUnit Selenium

Skill này hướng dẫn AI Agent cách viết thêm Test tự động mới cho dự án C# NUnit + Selenium, dựa trên dữ liệu Excel và file UI-Map. Khi thêm test cho một module mới, Agent CHỈ CẦN tạo 1 file (ví dụ EmployeeCreateTest.cs) và kế thừa từ BaseTest — vì BaseTest.cs và ExcelHelper.cs đã có sẵn trong dự án, không cần tạo lại.

1. Cấu Trúc Dự Án & Dependencies

NuGet Packages (kiểm tra file .csproj)

<PackageReference Include="NUnit" Version="4.*" />
<PackageReference Include="Selenium.WebDriver" Version="4.*" />
<PackageReference Include="Selenium.Support" Version="4.*" />
<PackageReference Include="EPPlus" Version="7.*" />
<PackageReference Include="NUnit3TestAdapter" Version="4.*" />

using Statements bắt buộc ở đầu mỗi file Test mới

using System;
using System.IO;
using NUnit.Framework;
using OfficeOpenXml;
using OpenQA.Selenium;

namespace TestProductGroup;   // namespace giống project gốc

Vị trí file

• Code Test: TestProductGroup/TestProductGroup/<ModuleName>Test.cs
• ExcelDumperTool: Công cụ riêng, chạy bằng CLI để trích xuất Excel → text
• Kế thừa: Mọi file Test ĐỀU PHẢI public class XYZTest : BaseTest

2. Các Lớp Dùng Chung (KHÔNG VIẾT LẠI)

BaseTest — Bắt buộc đọc examples/BaseTest.cs

Bạn được gọi trực tiếp trong class con:

ExcelHelper — Bắt buộc đọc examples/ExcelHelper.cs

Lớp static chứa logic xử lý Excel ở mức thấp. BaseTest chỉ là wrapper gọi tới đây. Agent không cần viết lại.

3. Quy Trình 4 Bước Viết Test Mới

⛔ Điều Kiện Tiên Quyết — Hỏi Trước Khi Làm

Trước khi thực hiện bất kỳ bước nào, Agent PHẢI kiểm tra và hỏi người dùng nếu chưa được cung cấp:

1. Đường dẫn file Excel (test data) — nếu chưa có, hỏi:

   "Bạn vui lòng cung cấp đường dẫn tuyệt đối đến file Excel chứa test cases (VD: D:\project\test-data.xlsx)?"

2. File UI-Map YAML (tọa độ các element trên UI) — nếu chưa có, hỏi:

   "Bạn vui lòng cung cấp nội dung hoặc đường dẫn file ui-map.yaml cho module cần viết test?"

Không được tự bịa hoặc giả định hai thông tin trên. Nếu thiếu một trong hai, dừng lại và hỏi trước.

Bước 1: Trích Xuất Dữ Liệu Excel

Chạy ExcelDumperTool và xuất ra file:

dotnet run --project "<ABSOLUTE_PATH_TO_EXCEL_DUMPER_TOOL>" -- "<ABSOLUTE_PATH_TO_EXCEL_FILE>" all > all_sheets_output.txt

Đọc file all_sheets_output.txt. Mỗi dòng có dạng:

R001:   [Cột1-MãTC]   [Cột2-Trường]   [Cột3]   [Cột4]   [Cột5-Input]   [Cột6-Expected]

Cột 5 = dữ liệu nhập vào, Cột 6 = kết quả kỳ vọng.

Bước 2: Đọc Tọa Độ UI (UI-Map)

Yêu cầu QA cung cấp ui-map.yaml. Tham khảo ui-map-template.yaml để hiểu format.

⚠️ Radix UI / Shadcn UI sinh ID dạng _r_6_ tự động, không ổn định. BẮT BUỘC dùng XPath Text cho combobox: //div[@role='option'][contains(text(), 'Giá trị')]

Bước 3: Tùy Biến Cho Module Mới (Checklist)

Trước khi sinh code, xác định các điểm cần thay đổi:

• Loại hành động: Xác định đây là loại test gì (Create / Edit / Delete / Search / Export / ...). Mỗi loại cần hàm điều hướng khác nhau (OpenCreateForm, OpenFirstEditForm, OpenSearchPage...). Không dùng mẫu của loại khác
• Cách đọc kết quả: Create/Edit/Delete thường đọc toast hoặc lỗi validation. Loại khác (VD: Search) có thể cần đọc số dòng trong bảng, nội dung cell, hoặc trạng thái hiển thị — hỏi người dùng nếu chưa rõ expected output là gì
• Tên sheet Excel: Sheet chứa test cases của module mới
• Mã TC prefix: VD: module Nhóm hàng dùng A-, B-, C-. Module mới có thể khác → sửa regex trong IsValidTestCaseCode (xem mục 5)
• URL điều hướng: Nếu module dùng URL khác /categories, cần thêm const và hàm Open...Form() trong class con
• ParseMultiField: Nếu dữ liệu Excel có nhiều trường (không chỉ Tên + Mô tả), phải viết hàm parse riêng (xem mục 5)
• Element IDs / Selectors: Lấy từ UI-Map, kiểm tra bằng DevTools

Bước 4: Sinh File Test C#

Tạo file tuân thủ cấu trúc:

1. [NonParallelizable] attribute trên class.
2. Class kế thừa BaseTest.
3. Hàm ExecuteCase(tcCode, field, rawData) → fill form → trả về string actual.
4. [Test] public void TestCases() → mở Excel bằng OpenExcelForWrite() → vòng lặp đọc Excel → gọi ExecuteCase → SaveCaseResult.

Lưu ý: Luôn dùng OpenExcelForWrite() thay vì new ExcelPackage(new FileInfo(ExcelPath)). Mặc định sẽ tự sao chép sang file mới có timestamp, giữ nguyên file test data gốc.

4. Edge Cases Quan Trọng

Quy ước fallbackIndex trong RequireWorksheet

RequireWorksheet tìm sheet theo tên (keyword) trước — fallbackIndex chỉ là lưới an toàn cuối cùng nếu không tìm thấy sheet theo tên.

⚠️ Không giả định thứ tự sheet. Số lượng và loại test (Create, Edit, Delete, Search, Export, ...) hoàn toàn phụ thuộc vào file Excel của từng dự án.

Nguyên tắc xác định fallbackIndex:

1. Ưu tiên dùng keyword — đặt keyword khớp với tên sheet thực tế trong Excel (VD: "Tìm kiếm", "Xuất dữ liệu").
2. Hỏi người dùng nếu chưa biết tên sheet — đừng tự đoán fallbackIndex.
3. Nếu biết thứ tự sheet (VD: sheet 0=Create, 1=Edit, 2=Delete, 3=Search), dùng đúng index đó.

Ví dụ dự án có 4 loại test:

// Create
var sheet = RequireWorksheet(package, "Thêm", fallbackIndex: 0);
// Edit
var sheet = RequireWorksheet(package, "Chỉnh sửa", fallbackIndex: 1);
// Delete
var sheet = RequireWorksheet(package, "Xóa", fallbackIndex: 2);
// Search — loại bổ sung, keyword ưu tiên
var sheet = RequireWorksheet(package, "Tìm kiếm", fallbackIndex: 3);

5. Cảnh Báo Quan Trọng — PHẢI ĐỌC

⚠️ IsValidTestCaseCode — Regex cứng theo module

// BaseTest.cs hiện tại:
Regex.IsMatch(tcCode, @"^[ABC]-\d{2}$")   // Chỉ khớp A-01, B-02, C-03...

Nếu module mới dùng mã khác (VD: EMP-01, D-01), bạn PHẢI override hoặc điều chỉnh logic này. Cách đơn giản nhất là đặt điều kiện check rộng hơn trong vòng lặp test của class con.

⚠️ ParseMultiField — Hardcode cho "Nhóm hàng hóa"

// ExcelHelper.cs hiện tại chỉ nhận biết:
line.StartsWith("Tên nhóm hàng hóa") → name
line.StartsWith("Mô tả")             → description

Nếu module mới có trường khác (VD: Nhân viên có Họ tên, Ngày sinh, Giới tính, Địa chỉ), hàm này sẽ trả về rỗng. Bạn cần viết hàm parse riêng trong class con hoặc file Helper mới.

Mẫu viết hàm parse riêng:

private (string fullName, string birthDate, string gender, string address) ParseEmployeeData(string raw)
{
    string fullName = "", birthDate = "", gender = "", address = "";
    if (string.IsNullOrWhiteSpace(raw)) return (fullName, birthDate, gender, address);

    var lines = raw.Replace("\r", "").Split('\n');
    foreach (var line in lines.Select(x => x.Trim()))
    {
        if (line.StartsWith("Họ tên", StringComparison.OrdinalIgnoreCase))
            fullName = line[(line.IndexOf(':') + 1)..].Trim();
        else if (line.StartsWith("Ngày sinh", StringComparison.OrdinalIgnoreCase))
            birthDate = line[(line.IndexOf(':') + 1)..].Trim();
        else if (line.StartsWith("Giới tính", StringComparison.OrdinalIgnoreCase))
            gender = line[(line.IndexOf(':') + 1)..].Trim();
        else if (line.StartsWith("Địa chỉ", StringComparison.OrdinalIgnoreCase))
            address = line[(line.IndexOf(':') + 1)..].Trim();
    }
    return (fullName, birthDate, gender, address);
}

6. Tham Khảo Code Mẫu

Thứ tự đọc bắt buộc: BaseTest.cs → ExcelHelper.cs → ProductGroupCreateTest.cs → ProductGroupEditTest.cs → ProductGroupDeleteTest.cs → viết file mới.