WAF4RPA User Guide

1. Giới thiệu

WAF4RPA là framework web automation lightweight dựa trên Playwright, được thiết kế cho:

• web automation,
• small-scale RPA applications,
• học tập và nghiên cứu,
• rapid prototyping,
• data-driven automation.

Framework hỗ trợ:

• workflow-driven execution bằng YAML,
• reusable automation actions,
• Excel data integration,
• browser automation thông qua Playwright,
• screenshot và logging,
• extensible custom actions,
• CLI execution,
• npm package integration.

2. Yêu cầu hệ thống

• Node.js >= 18

• npm >= 9

• Hệ điều hành:

  • Windows
  • Linux
  • macOS

3. Cài đặt

3.1. Cài đặt package

npm install waf4rpa

3.2. Cài đặt Playwright browsers

npx playwright install

4. Chạy workflow bằng CLI

4.1. Tạo workflow YAML

Ví dụ file:

workflow.yaml

4.2. Nội dung workflow

steps:

  - action: openBrowser

  - action: navigate
    url: https://example.com

  - action: screenshot

  - action: closeBrowser

4.3. Thực thi workflow

waf4rpa run workflow.yaml

5. Built-in Actions

WAF4RPA cung cấp các built-in actions phục vụ browser automation cơ bản.

| Action | Mô tả | | ------------ | -------------------- | | openBrowser | Khởi tạo browser | | closeBrowser | Đóng browser | | navigate | Điều hướng URL | | click | Click element | | type | Nhập dữ liệu | | wait | Delay | | screenshot | Chụp screenshot | | loadExcel | Đọc dữ liệu từ Excel | | radio | Chọn radio button | | press | Keyboard key press |

6. Ví dụ browser automation

6.1. Form automation

steps:

  - action: openBrowser

  - action: navigate
    url: https://demoqa.com/automation-practice-form

  - action: type
    selector: '#firstName'
    value: John

  - action: type
    selector: '#lastName'
    value: Doe

  - action: screenshot

  - action: closeBrowser

7. Data-driven Automation với Excel

7.1. Chuẩn bị dữ liệu Excel

Ví dụ:

data/students.xlsx

| firstName | lastName | email | | --------- | -------- | ------------------------------------------- | | John | Doe | [email protected] |

7.2. Workflow sử dụng Excel

steps:

  - action: loadExcel
    file: ./data/students.xlsx

  - action: openBrowser

  - action: navigate
    url: https://demoqa.com/automation-practice-form

  - action: type
    selector: '#firstName'
    value: ${currentRow.firstName}

  - action: type
    selector: '#lastName'
    value: ${currentRow.lastName}

  - action: type
    selector: '#userEmail'
    value: ${currentRow.email}

  - action: screenshot

  - action: closeBrowser

8. Sử dụng WAF4RPA như SDK

Ngoài CLI execution, WAF4RPA có thể được sử dụng như reusable TypeScript library bên trong application.

8.1. Ví dụ sử dụng SDK

import {
  WorkflowRunner,
  registerDefaultActions
} from 'waf4rpa';

async function bootstrap() {

  const runner =
    new WorkflowRunner();

  registerDefaultActions(
    runner
  );

  await runner.run(
    './workflow.yaml'
  );
}

bootstrap();

9. Custom Actions

WAF4RPA hỗ trợ mở rộng custom actions ở cấp application.

Framework chỉ cung cấp các generic actions. Các business-specific logic sẽ được triển khai tại consumer application.

9.1. Tạo custom action

Ví dụ:

actions/fill-student.action.ts

9.2. Nội dung custom action

import {
  Action,
  ExecutionContext
} from 'waf4rpa';

export class FillStudentAction
  implements Action {

  async execute(
    context: ExecutionContext
  ): Promise<void> {

    if (!context.sdk) {
      throw new Error(
        'SDK not initialized'
      );
    }

    const student =
      context.variables.currentRow;

    await context.sdk.type(
      '#firstName',
      student.firstName
    );

    await context.sdk.type(
      '#lastName',
      student.lastName
    );

    await context.sdk.type(
      '#userEmail',
      student.email
    );
  }
}

10. Register Custom Action

10.1. Đăng ký action

import {
  WorkflowRunner,
  registerDefaultActions
} from 'waf4rpa';

import {
  FillStudentAction
} from './actions/fill-student.action';

async function bootstrap() {

  const runner =
    new WorkflowRunner();

  registerDefaultActions(
    runner
  );

  runner.register(
    'fillStudent',
    new FillStudentAction()
  );

  await runner.run(
    './workflow.yaml'
  );
}

bootstrap();

10.2. Sử dụng trong workflow

steps:

  - action: fillStudent