ProcessMaker TestBench CI Testing

Automated testing skill for ProcessMaker 4 CI instances. Provides smoke testing, API validation, and server configuration capabilities through a TypeScript CLI tool.

Purpose

Run comprehensive automated tests against remote ProcessMaker 4 servers, including:

API calls with bearer token authentication

Playwright browser automation tests

Server environment updates and configuration

Token generation for authentication

Project Architecture

The TestBench CLI follows this structure:

**Entry Point**: `src/index.ts` - Main CLI using Commander.js

**Commands**:

- `update-server` - Updates remote server environment via API calls (non-interactive)

- `smoketest` - Runs end-to-end tests against the configured server

- `get-token` - Generates bearer tokens for server authentication

**Configuration**: `config.ts` - Environment variable management

**Actions**: `src/actions/` - Executable scripts for server setup and configuration

**Playwright Actions**: `src/actions/playwright/` - Browser automation scripts for server setup when API is insufficient

**End-to-End Tests**: `src/tests/` - Test suites that validate server functionality

**Unit Tests**: `src/__tests__/` - Tests for internal project components

Instructions

When working with ProcessMaker TestBench projects:

1. Environment Setup

**ALWAYS** validate these required environment variables on startup:

- `SERVER_URL`: Remote ProcessMaker server URL

- `BEARER_TOKEN`: Authentication token for API calls

Use `dotenv` for environment variable management

Provide clear error messages if required variables are missing

2. Command Implementation

When building or modifying commands:

**update-server command**:

- Default behavior: Run ALL scripts in `src/actions/` (excluding subfolders) sequentially

- Support `--script` flag to run a single specific script (e.g., `--script=configure-email`)

- MUST be non-interactive (no user prompts or selections)

- Stop execution on first error with clear error message

- Example: `npm run update-server` or `npm run update-server -- --script=configure-email`

**smoketest command**:

- Execute Playwright tests from `src/tests/` directory

- Validate actual server functionality

- Report test results clearly

**get-token command**:

- Use Playwright to generate bearer tokens for authentication

- Store or display tokens for use in other commands

3. Action Scripts

When writing action scripts in `src/actions/`:

Make scripts self-contained and non-interactive

Use axios for API calls with bearer token authentication

Handle errors gracefully with descriptive messages

Use async/await for all asynchronous operations

Place Playwright-based actions in `src/actions/playwright/` subfolder

4. Test Organization

Follow this test structure:

**`src/tests/`**: End-to-end tests that validate actual server functionality

- Test user workflows, API endpoints, UI interactions

- Use Playwright for browser automation

- Focus on real-world scenarios

**`src/__tests__/`**: Unit tests for internal project components

- Test utilities, actions, command logic

- Use vitest as the testing framework

- Mock external dependencies

**`src/actions/playwright/`**: Browser automation for server setup

- NOT tests - these are setup/configuration scripts

- May include assertions for validation

- Used when API calls are insufficient

5. Code Quality Standards

Follow TypeScript strict mode guidelines

Use proper error handling throughout

Support verbose logging for debugging (`--verbose` flag)

Provide user-friendly error messages

Use Commander.js for CLI framework

Use axios for HTTP client operations

Use Playwright for browser automation

6. Development Workflow

Use these npm scripts:

```bash

Development with hot reload

npm run dev

Build TypeScript

npm run build

Run compiled version

npm start

Run unit tests (vitest)

npm test

Run end-to-end tests (playwright)

npm run smoketest

Update server configuration (all scripts)

npm run update-server

Update server configuration (specific script)

npm run update-server -- --script=configure-email

Generate authentication token

npm run get-token

```

7. Key Dependencies

Always include these in the project:

**commander**: CLI framework

**playwright**: Browser automation for testing

**axios**: HTTP client for API calls

**dotenv**: Environment variable management

**vitest**: Unit testing framework

**typescript**: TypeScript compiler and tooling

8. Best Practices

Validate environment variables at startup before any operations

Always use async/await for asynchronous operations

Provide clear error messages with actionable guidance

Keep actions independent and reusable

Separate concerns: setup actions vs. validation tests

Use sequential execution for dependent operations

Log important steps when verbose mode is enabled

Handle authentication errors specifically (401, 403)

Test both success and failure paths

Example Usage

```bash

Set up environment

export SERVER_URL=https://pm4-instance.example.com

export BEARER_TOKEN=your_token_here

Run full server configuration

npm run update-server

Run specific configuration script

npm run update-server -- --script=configure-email

Execute smoke tests

npm run smoketest

Generate new auth token

npm run get-token

Run unit tests

npm test

```

Common Patterns

Action Script Template

```typescript

import axios from 'axios';

import { config } from '../config';

export async function actionName() {

try {

const response = await axios.post(

`${config.serverUrl}/api/endpoint`,

{ data },

{

headers: {

'Authorization': `Bearer ${config.bearerToken}`,

'Content-Type': 'application/json'

}

);

console.log('✓ Action completed successfully');

return response.data;

} catch (error) {

console.error('✗ Action failed:', error.message);

throw error;

}

```

E2E Test Template

```typescript

import { test, expect } from '@playwright/test';

import { config } from '../config';

test('feature validation', async ({ page }) => {

await page.goto(config.serverUrl);

// Test implementation

await expect(page.locator('selector')).toBeVisible();

});

```

ProcessMaker TestBench CI Testing

ProcessMaker TestBench CI Testing

Purpose

Project Architecture

Instructions

1. Environment Setup

2. Command Implementation

3. Action Scripts

4. Test Organization

5. Code Quality Standards

6. Development Workflow

Development with hot reload

Build TypeScript

Run compiled version

Run unit tests (vitest)

Run end-to-end tests (playwright)

Update server configuration (all scripts)

Update server configuration (specific script)

Generate authentication token

7. Key Dependencies

8. Best Practices

Example Usage

Set up environment

Run full server configuration

Run specific configuration script

Execute smoke tests

Generate new auth token

Run unit tests

Common Patterns

Action Script Template

E2E Test Template

Reviews (0)