TestBlocks

A visual test automation tool using Blockly for building API and web (Playwright) tests. Design tests visually, save them as JSON files for version control, and run them in CI with the CLI runner.

Features

• Visual Test Builder - Drag-and-drop blocks to create tests without coding
• API Testing - Built-in blocks for HTTP requests (GET, POST, PUT, PATCH, DELETE) and assertions
• Web Testing - Playwright-powered blocks for browser automation (navigate, click, type, assertions)
• Git-Friendly - Tests saved as JSON files that can be versioned in repositories
• CLI Runner - Run tests in CI/CD pipelines with JUnit/JSON reports
• Extensible - Create custom blocks with the plugin system

Quick Start

Installation

# Install dependencies
npm install

# Build all packages
npm run build

# Install Playwright browsers
npx playwright install chromium

Development

# Start the development server (frontend + backend)
npm run dev

Open http://localhost:3000 in your browser to use the visual editor.

Running Tests

# Run tests via CLI
npm run cli run "examples/tests/*.testblocks.json"

# Run with headed browser (visible)
npm run cli run tests/*.testblocks.json --headed

# Run with JUnit output for CI
npm run cli run tests/*.testblocks.json --reporter junit --output ./results

# Validate test files
npm run cli validate "examples/tests/*.testblocks.json"

# List tests in files
npm run cli list "examples/tests/*.testblocks.json"

Project Structure

testblocks/
├── src/
│   ├── core/          # Types, block definitions, plugin system
│   ├── client/        # React + Blockly visual editor
│   ├── server/        # Express server for test execution
│   └── cli/           # CLI runner for CI integration
├── examples/
│   ├── tests/         # Example test files
│   └── plugins/       # Example custom plugins
└── testblocks.config.json

Test File Format

Tests are stored as .testblocks.json files:

{
  "version": "1.0.0",
  "name": "My Test Suite",
  "variables": {
    "baseUrl": { "type": "string", "default": "https://example.com" }
  },
  "beforeAll": [],
  "afterAll": [],
  "beforeEach": [],
  "afterEach": [],
  "procedures": {
    "login": {
      "name": "login",
      "params": [{ "name": "username", "type": "string" }],
      "steps": []
    }
  },
  "tests": [
    {
      "id": "test-1",
      "name": "Login test",
      "data": [
        { "name": "admin", "values": { "username": "admin", "password": "123" } },
        { "name": "user", "values": { "username": "user", "password": "456" } }
      ],
      "steps": []
    }
  ]
}

Lifecycle Hooks

TestBlocks supports setup/teardown hooks at multiple levels:

Hook	Level	Description
beforeAll	Suite	Runs once before all tests
afterAll	Suite	Runs once after all tests
beforeEach	Suite	Runs before each test
afterEach	Suite	Runs after each test
beforeEach	Test	Runs before this specific test
afterEach	Test	Runs after this specific test

Data-Driven Testing

Run the same test with different data sets:

{
  "id": "test-login",
  "name": "Login with credentials",
  "data": [
    { "name": "admin user", "values": { "username": "admin", "password": "admin123" } },
    { "name": "regular user", "values": { "username": "user1", "password": "pass123" } }
  ],
  "steps": []
}

Access data values using data_get_current block with the key name, or use ${username} variable syntax.

Custom Procedures

Define reusable action sequences (like functions):

{
  "procedures": {
    "login": {
      "name": "login",
      "description": "Login with credentials",
      "params": [
        { "name": "username", "type": "string" },
        { "name": "password", "type": "string" }
      ],
      "steps": []
    }
  }
}

Call procedures using the procedure_call block with arguments.

Built-in Blocks

API Blocks

Block	Description
GET	Perform HTTP GET request
POST	Perform HTTP POST request
PUT	Perform HTTP PUT request
PATCH	Perform HTTP PATCH request
DELETE	Perform HTTP DELETE request
Assert Status	Assert response status code
Assert Body Contains	Assert response body contains value
Extract Value	Extract value from response using JSON path
Headers	Create headers with authentication
JSON Body	Create JSON request body

Web (Playwright) Blocks

Block	Description
Navigate	Navigate to URL
Click	Click an element
Fill	Fill input field (clears first)
Type	Type text character by character
Select	Select dropdown option
Checkbox	Check/uncheck checkbox
Hover	Hover over element
Press Key	Press keyboard key
Wait for Element	Wait for element state
Wait for URL	Wait for URL to match
Wait	Pause for specified time
Screenshot	Take screenshot
Get Text	Get element text content
Get Attribute	Get element attribute
Assert Visible	Assert element is visible
Assert Text Contains	Assert element text contains value
Assert Text Equals	Assert element text equals value
Assert URL Contains	Assert URL contains value
Assert Title Contains	Assert page title contains value

Logic Blocks

Block	Description
Set Variable	Set a variable value
Get Variable	Get a variable value
If	Conditional execution
Compare	Compare two values
Repeat	Repeat blocks N times
For Each	Iterate over array
Try/Catch	Handle errors
Log	Log a message
Assert	Assert condition is true
Fail	Fail the test

CLI Options

Usage: testblocks run [options] <patterns...>

Run test files

Options:
  -H, --headed           Run in headed mode (show browser)
  -t, --timeout <ms>     Test timeout in milliseconds (default: 30000)
  -r, --reporter <type>  Reporter: console, json, junit (default: console)
  -o, --output <dir>     Output directory for reports
  -b, --base-url <url>   Base URL for relative URLs
  -v, --var <vars...>    Variables in key=value format
  --fail-fast            Stop on first test failure
  --filter <pattern>     Only run tests matching pattern

Creating Custom Plugins

Create plugins to add custom blocks:

import { createPlugin, createBlock, registerPlugin } from '@testblocks/core';

const myPlugin = createPlugin({
  name: 'my-plugin',
  version: '1.0.0',
  description: 'My custom blocks',
  blocks: [
    createBlock({
      type: 'my_custom_block',
      category: 'Custom',
      color: '#9C27B0',
      tooltip: 'My custom action',
      inputs: [
        { name: 'VALUE', type: 'field', fieldType: 'text', required: true },
      ],
      previousStatement: true,
      nextStatement: true,
      execute: async (params, context) => {
        context.logger.info(`Custom block executed with: ${params.VALUE}`);
      },
    }),
  ],
});

registerPlugin(myPlugin);

Configuration

Create testblocks.config.json in your project root:

{
  "testDir": "./tests",
  "testMatch": ["**/*.testblocks.json"],
  "timeout": 30000,
  "headless": true,
  "reporter": "console",
  "outputDir": "./testblocks-results",
  "variables": {
    "baseUrl": "http://localhost:3000"
  },
  "plugins": []
}

CI/CD Integration

GitHub Actions

name: Tests
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: '20'

      - run: npm ci
      - run: npm run build
      - run: npx playwright install chromium

      - run: npm run cli run "tests/**/*.testblocks.json" --reporter junit --output results

      - uses: actions/upload-artifact@v4
        if: always()
        with:
          name: test-results
          path: results/

GitLab CI

test:
  image: mcr.microsoft.com/playwright:v1.49.0
  script:
    - npm ci
    - npm run build
    - npm run cli run "tests/**/*.testblocks.json" --reporter junit --output results
  artifacts:
    reports:
      junit: results/junit.xml

License

MIT