Testing - Oyasai Server Platform

Overview

Oyasai Server Platform provides multiple approaches for testing:

Local Purpur Server: Test plugins in a real Minecraft environment
Nix Flake Checks: Automated build and test validation
CI Pipeline: Continuous integration testing

Local Purpur Server Testing

Using oyasai-minecraft-minimal

The oyasai-minecraft-minimal package is designed for local plugin testing.

1. Configure Your Test Server

Edit packages/oyasai-minecraft-minimal.nix:

{ oyasaiPurpur, oyasai-plugin-registry }:
let
  inherit (oyasaiScope.plugins) 
    oyasaiutilities 
    dynamicprofile
    oyasaipets;
in
oyasaiPurpur rec {
  name = "oyasai-minecraft-minimal";
  version = "1.21.8";
  directory = "local";

  plugins = with (oyasai-plugin-registry.forVersion version); [
    essentialsx
    fastasyncworldedit
    plugmanx
  ] ++ [
    # Add your plugins here
    oyasaiutilities
    dynamicprofile
  ];
}

The oyasai-minecraft-minimal configuration is meant to be customized for your testing needs. The file is referenced in CONTRIBUTING.md:58 as the testing template.

2. Build Your Plugins

gradle build --parallel

Or build a specific plugin:

gradle :plugins:OyasaiUtilities:build

3. Run the Test Server

nix run .#oyasai-minecraft-minimal

The server will:

Create the local/ directory
Install all configured plugins
Accept the EULA automatically
Start Purpur 1.21.8 on port 25565

4. Connect and Test

Connect to localhost:25565 with your Minecraft client (version 1.21.8).

Custom Test Configurations

Create a dedicated test configuration:

1. Create Test Package

nano packages/oyasai-minecraft-test.nix

{ oyasaiPurpur, oyasai-plugin-registry }:
let
  inherit (oyasaiScope.plugins) myplugin;
in
oyasaiPurpur rec {
  name = "oyasai-minecraft-test";
  version = "1.21.8";
  directory = "test-server";
  port = 25566;  # Different port

  plugins = with (oyasai-plugin-registry.forVersion version); [
    essentialsx
  ] ++ [
    myplugin  # Your plugin under test
  ];
}

2. Register and Run

Stage the file:

git add packages/oyasai-minecraft-test.nix

Add to nix/oyasai-scope.nix exports if desired, then:

nix run .#oyasai-minecraft-test

Iterative Development Workflow

Fast Iteration Loop

Make Code Changes to your plugin
Rebuild Plugin:
```
gradle :plugins:MyPlugin:build
```
Update Nix Lock (if dependencies changed):
```
gradle2nix
```
Rebuild Server Package:
```
nix build .#oyasai-minecraft-minimal
```
Restart Server:
```
nix run .#oyasai-minecraft-minimal
```
Test In-Game

Hot Reloading Plugins

Use PlugManX for hot reloading during development:

Include plugmanx in your test server configuration
Build your plugin:
```
gradle :plugins:MyPlugin:shadowJar
```

Copy to server:

cp plugins/MyPlugin/build/libs/MyPlugin.jar local/plugins/

In-game or console:
```
/plugman reload MyPlugin
```

Hot reloading doesn’t always work cleanly. For major changes, restart the server.

Testing Specific Features

Testing Commands

Start the server with your plugin
Join the server
Run commands in-game or via console:
```
/your-command arg1 arg2
```
Check server logs for output

Testing Event Listeners

Enable debug logging in your plugin:

logger.info("Event triggered: ${event.javaClass.simpleName}")

Trigger the event in-game (join, break block, etc.)
Check local/logs/latest.log

Testing Configuration Files

Run server once to generate default config:
```
nix run .#oyasai-minecraft-minimal
```
Stop server and modify local/plugins/YourPlugin/config.yml
Restart and verify changes are applied

Testing Database Integration

For plugins with database dependencies:

{ oyasaiPurpur, oyasai-plugin-registry }:

oyasaiPurpur rec {
  name = "test-with-db";
  version = "1.21.8";
  directory = "test-db";
  
  plugins = with (oyasai-plugin-registry.forVersion version); [
    essentialsx
    # Add your database plugin
  ];
}

Run a local MariaDB or MySQL server and configure your plugin to connect.

Nix Flake Checks

Running All Checks

nix flake check -L

This command:

Builds all packages
Builds all plugins
Runs any defined tests
Validates Nix expressions

See CONTRIBUTING.md:46-50.

Check Output

• building build-oyasai-minecraft-main
• building build-oyasai-minecraft-minimal
• building build-plugins-batch
• building build-oyasaiutilities
• building build-dynamicprofile
...

Checking Specific Packages

nix build .#oyasai-minecraft-minimal --rebuild

Continuous Integration

The CI pipeline automatically runs on all pull requests.

CI Checks

Build Validation: All packages must build successfully
Format Checking: Code must be formatted (see below)
Lockfile Sync: gradle.lock must be up to date

Format Checking

Code must be formatted before committing:

nix fmt

This formats:

Nix files (.nix)
Kotlin files (.kt)
Other configured file types

See CONTRIBUTING.md:33-37.

Pre-Commit Validation

Before pushing, run:

nix fmt
nix flake check -L

If both pass, your PR will likely pass CI.

Debugging

Server Logs

Check local/logs/latest.log for server output:

tail -f local/logs/latest.log

Plugin Logs

Add logging to your plugin:

class MyPlugin : JavaPlugin() {
  override fun onEnable() {
    logger.info("${description.name} enabled")
    logger.warning("This is a warning")
    logger.severe("This is an error")
  }
}

Verbose Nix Output

For build debugging:

nix build .#oyasai-minecraft-minimal --print-build-logs

Or with checks:

nix flake check -L  # -L shows build logs

Gradle Debug

Enable Gradle debug output:

gradle build --debug

Or for specific tasks:

gradle :plugins:MyPlugin:build --debug

Common Testing Scenarios

Testing Plugin Interactions

Test how multiple plugins interact:

plugins = [
  plugin1
  plugin2  # Depends on plugin1
];

Verify:

Load order is correct
Events fire in expected sequence
Shared resources don’t conflict

Testing with External Plugins

Test your plugin alongside popular external plugins:

plugins = with (oyasai-plugin-registry.forVersion version); [
  vault          # Economy API
  luckperms      # Permissions
  essentialsx    # Core functionality
] ++ [
  yourplugin     # Your plugin
];

Performance Testing

For load testing:

Configure server with JVM options:

nix run .#oyasai-minecraft-minimal -- -Xmx2G -Xms2G

Use tools like spark plugin for profiling
Monitor local/logs/latest.log for lag warnings

Best Practices

1. Isolate Test Environments

Use separate directories for different test configurations:

directory = "test-feature-a";  # One server
directory = "test-feature-b";  # Another server

2. Clean State Testing

For clean testing, delete the server directory:

rm -rf local/
nix run .#oyasai-minecraft-minimal

3. Version Testing

If supporting multiple Minecraft versions:

# Test on 1.21.8
oyasaiPurpur { version = "1.21.8"; ... }

# Future: Test on other versions
# oyasaiPurpur { version = "1.22.0"; ... }

4. Document Test Cases

Create test documentation in your plugin:

plugins/MyPlugin/docs/
├── testing.md
└── test-cases.md

5. Automated Testing

For unit tests, use JUnit in your plugin:

// src/test/kotlin/MyPluginTest.kt
import org.junit.jupiter.api.Test
import kotlin.test.assertEquals

class MyPluginTest {
  @Test
  fun testFeature() {
    assertEquals(expected, actual)
  }
}

Run tests:

gradle :plugins:MyPlugin:test

Troubleshooting

Server Won’t Start

Check Java version:
```
which java
java -version
```
Check port availability:
```
lsof -i :25565
```
Review logs:
```
cat local/logs/latest.log
```

Plugin Not Loading

Verify plugin is in configuration:

plugins = [ myplugin ];  # Is your plugin here?

Check build output:
```
ls -la plugins/MyPlugin/build/libs/
```
Check server plugins directory:
```
ls -la local/plugins/
```

Check server console:

[INFO] Loading plugins (X)
[INFO] Enabling MyPlugin vX.X.X

Gradle Lock Out of Sync

gradle2nix
git diff gradle.lock  # Review changes
git add gradle.lock

Next Steps

Plugin Development

Continue developing your plugins

Contributing

Submit your tested changes

Gradle Workflow

Deep dive into build system

Nix Packages

Create advanced server configurations

Overview

Setup & Deployment

Architecture

Plugins

Operations

Development

​Overview

​Local Purpur Server Testing

​Using oyasai-minecraft-minimal

​1. Configure Your Test Server

​2. Build Your Plugins

​3. Run the Test Server

​4. Connect and Test

​Custom Test Configurations

​1. Create Test Package

​2. Register and Run

​Iterative Development Workflow

​Fast Iteration Loop

​Hot Reloading Plugins

​Testing Specific Features

​Testing Commands

​Testing Event Listeners

​Testing Configuration Files

​Testing Database Integration

​Nix Flake Checks

​Running All Checks

​Check Output

​Checking Specific Packages

​Continuous Integration

​CI Checks

​Format Checking

​Pre-Commit Validation

​Debugging

​Server Logs

​Plugin Logs

​Verbose Nix Output

​Gradle Debug

​Common Testing Scenarios

​Testing Plugin Interactions

​Testing with External Plugins

​Performance Testing

​Best Practices

​1. Isolate Test Environments

​2. Clean State Testing

​3. Version Testing

​4. Document Test Cases

​5. Automated Testing

​Troubleshooting

​Server Won’t Start

​Plugin Not Loading

​Gradle Lock Out of Sync

​Next Steps

Plugin Development

Contributing

Gradle Workflow

Nix Packages

Build docs developers (and LLMs) love

Overview

Local Purpur Server Testing

Using oyasai-minecraft-minimal

1. Configure Your Test Server

2. Build Your Plugins

3. Run the Test Server

4. Connect and Test

Custom Test Configurations

1. Create Test Package

2. Register and Run

Iterative Development Workflow

Fast Iteration Loop

Hot Reloading Plugins

Testing Specific Features

Testing Commands

Testing Event Listeners

Testing Configuration Files

Testing Database Integration

Nix Flake Checks

Running All Checks

Check Output

Checking Specific Packages

Continuous Integration

CI Checks

Format Checking

Pre-Commit Validation

Debugging

Server Logs

Plugin Logs

Verbose Nix Output

Gradle Debug

Common Testing Scenarios

Testing Plugin Interactions

Testing with External Plugins

Performance Testing

Best Practices

1. Isolate Test Environments

2. Clean State Testing

3. Version Testing

4. Document Test Cases

5. Automated Testing

Troubleshooting

Server Won’t Start

Plugin Not Loading

Gradle Lock Out of Sync

Next Steps