Home | Pilaf documentation

Table of Contents

Pilaf Documentation

Pilaf Documentation

License: MIT

Welcome to Pilaf (Paper Integration Layer for Automation Functions), a testing framework for PaperMC Minecraft plugins. Pilaf provides simple, readable JavaScript test scenarios.

Why Pilaf?

Pilaf makes PaperMC plugin testing straightforward with:

JavaScript Tests - Write tests in familiar JavaScript
Declarative Stories - Describe what to test, not how
Two Backends - RCON for server commands, Mineflayer for player simulation
Jest Integration - Leverage familiar Jest testing patterns
Rich Assertions - Entities, inventory, position, and more
HTML Reports - Vue.js-based interactive test reports

Quick Example

const { describe, it, expect } = require('@jest/globals');
const { StoryRunner } = require('@pilaf/framework');

describe('My Plugin', () => {
  it('should execute plugin commands', async () => {
    const runner = new StoryRunner();

    const story = {
      name: 'Plugin Command Test',
      setup: {
        server: { type: 'paper', version: '1.21.8' },
        players: [{ name: 'Test Player', username: 'tester' }]
      },
      steps: [
        {
          name: 'Make player operator',
          action: 'execute_command',
          command: 'op tester'
        },
        {
          name: 'Execute plugin command',
          action: 'execute_player_command',
          player: 'tester',
          command: '/myplugin command'
        },
        {
          name: 'Verify result',
          action: 'assert',
          condition: 'contains',
          expected: 'success',
          actual: '{previous_result}'
        }
      ],
      teardown: { stop_server: false }
    };

    const result = await runner.execute(story);
    expect(result.success).toBe(true);
  });
});

Key Features

RCON Backend - Execute server commands via RCON protocol
Mineflayer Backend - Simulate players with realistic behavior
Variable Storage - Store and reference values between steps
Rich Actions - 20+ built-in actions for common test scenarios
Comprehensive Assertions - Entities, inventory, position, numeric comparisons
Jest Integration - Use familiar Jest patterns and reporters

Quick Start

# Install Pilaf
pnpm add -D @pilaf/framework @pilaf/backends @pilaf/cli

# Run your first test
pilaf test my-first-test.pilaf.test.js

See Quick Start Guide for details.

Architecture

                    Jest Test Runner
                          │
                          ▼
                    ┌───────────────┐
                    │  StoryRunner  │
                    │  (Framework)  │
                    └───────┬───────┘
                            │
              ┌─────────────┼─────────────┐
              │             │             │
              ▼             ▼             ▼
      ┌───────────┐ ┌───────────┐ ┌─────────────┐
      │   RCON    │ │Mineflayer │ │   Reporter   │
      │  Backend  │ │  Backend  │ │  (Vue.js)    │
      └─────┬─────┘ └─────┬─────┘ └─────────────┘
            │             │
            └─────────────┼──────────────────┐
                          │                  │
                          ▼                  ▼
                ┌─────────────────┐  ┌─────────────┐
                │ PaperMC Server  │  │   HTML      │
                │  (1.21.8+)      │  │   Reports   │
                │  RCON: 25575    │  └─────────────┘
                └─────────────────┘

See Architecture Overview for details.