Table of Contents

• Pilaf Documentation
• Why Pilaf?
  • Problem: Complex Integration Testing
  • Solution: YAML Story Format
  • Key Benefits
• Supported Backends
• Quick Start
• Documentation Structure
  • Core Topics
  • Tutorials
  • Guides
  • References
• Pilaf Actions
  • Server Actions
  • Player Actions
  • Story Actions
• Key Features
• System Architecture
• Requirements
• Installation
• Getting Help
• License

Pilaf Documentation

Welcome to Pilaf (Paper Integration Layer for Automation Functions), a comprehensive YAML story-driven testing framework specifically designed for PaperMC Minecraft plugin developers. Pilaf transforms complex Java integration tests into simple, readable YAML scenarios that enable automated testing of Minecraft plugin functionality.

Why Pilaf?

Problem: Complex Integration Testing

Traditional PaperMC plugin testing requires extensive Java code to simulate player actions, execute server commands, and validate results.

A single integration test can require 150+ lines of complex Java code that:

• Simulate player connections and actions

• Execute server commands via RCON

• Handle asynchronous responses

• Clean up test data

• Manage server lifecycle

Solution: YAML Story Format

Pilaf eliminates this complexity by providing a YAML-based story format:

name: "Test Lightning Ability"
steps:
  - action: "execute_rcon_command"
    command: "op test_player"
  - action: "send_chat"
    player: "test_player"
    message: "/lightning"
  - action: "wait"
    seconds: 2
  - action: "check_log"
    pattern: "Lightning struck"
    assertions:
      - type: "assert_match"
        pattern: "Lightning struck"

Key Benefits

• Human-Readable: YAML stories that non-developers can understand and maintain

• Declarative: Describe what to test rather than how to test it

• Multi-Backend: Support for Docker, Mineflayer, and HeadlessMc backends

• Comprehensive: Rich assertions, state capture, and comparison capabilities

• CI/CD Ready: Seamless integration with GitHub Actions and other CI systems

Supported Backends

Backend	Description
Docker Backend	Launches PaperMC server using Docker Compose with RCON support
Mineflayer Backend	Headless JavaScript client for realistic player simulation
HeadlessMc Backend	Self-contained Java backend for CI/CD environments

Quick Start

# Clone the repository
git clone https://github.com/cavarest/pilaf.git
cd pilaf

# Build the project
./gradlew build

# Run a test story
./gradlew run --args="--backend docker demo-story.yaml"

See the 5-Minute Quick Start Guide for a step-by-step tutorial.

Documentation Structure

Core Topics

Essential concepts and architecture for understanding Pilaf.

Tutorials

Step-by-step guides to help you get started and accomplish specific tasks.

Guides

In-depth guides for writing stories, best practices, and advanced usage.

References

Complete command reference for all server actions, player actions, and assertions.

Pilaf Actions

Server Actions

Execute RCON commands on the Minecraft server:

• execute_rcon_command - Run any RCON command

• check_server_property - Verify server configuration

• wait_for_log - Wait for specific log patterns

• get_server_info - Retrieve server status and information

Player Actions

Simulate player interactions through connected clients:

• send_chat - Send chat messages as a player

• move_player - Move player to specific coordinates

• give_item - Give items to players

• attack_entity - Simulate player attacks

• And more…​

Story Actions

Control story flow and validation:

• wait - Pause execution for specified duration

• capture_state - Store server or player state

• assert_state - Compare captured states

• assert_log - Verify log patterns

• assert_chat - Check chat message content

Key Features

• YAML Story DSL: Human-readable test scenarios

• Multi-Player Support: Test interactions between multiple players

• State Management: Capture and compare server/player states

• Rich Assertions: Log, chat, entity, and inventory validation

• Backend Abstraction: Switch between Docker, Mineflayer, and HeadlessMc

• Comprehensive Reporting: HTML and JUnit XML report generation

• GitHub Actions Integration: Ready-made CI/CD workflows

System Architecture

                        Pilaf Test Framework
                              │
              ┌───────────────┼───────────────┐
              │               │               │
              ▼               ▼               ▼
      ┌───────────┐   ┌───────────┐   ┌───────────┐
      │   Docker  │   │ Mineflayer│   │HeadlessMc │
      │  Backend  │   │  Backend  │   │  Backend  │
      └─────┬─────┘   └─────┬─────┘   └─────┬─────┘
            │               │               │
            └───────────────┼───────────────┘
                            │
                            ▼
              ┌─────────────────────────────┐
              │    Minecraft Server         │
              │    (PaperMC 1.20.4+)        │
              └─────────────────────────────┘
                            │
                            ▼
              ┌─────────────────────────────┐
              │      RCON Interface         │
              │      Port: 25575            │
              └─────────────────────────────┘

See Architecture Overview for detailed system design.

Requirements

• Java 21 (LTS) or later

• Docker and Docker Compose (for Docker backend)

• Node.js 16+ (for Mineflayer backend)

• Gradle 8.x

Installation

See the Installation Guide for detailed setup instructions.

Getting Help

• GitHub Issues: Report bugs or request features

• GitHub Repository: View source code

• Documentation: Live documentation

License

Pilaf is open source under the MIT License.