@pilaf/framework 1.0.1 → 1.2.0

package/README.md

@@ -16,6 +16,42 @@ pnpm add @pilaf/framework
 pnpm add -D jest@^29.0.0
 ```
 
+## Quick Start - Bot Player Testing
+
+The simplest way to test with bot players:
+
+```javascript
+const { createTestContext, cleanupTestContext } = require('@pilaf/framework');
+
+describe('My Plugin Tests', () => {
+  let context;
+
+  beforeAll(async () => {
+    // Creates RCON connection + bot player in one call
+    context = await createTestContext({
+      username: 'TestPlayer',
+      host: 'localhost',
+      gamePort: 25565,
+      rconPort: 25575,
+      rconPassword: 'minecraft'
+    });
+  });
+
+  afterAll(async () => {
+    await cleanupTestContext(context);
+  });
+
+  it('should execute command as bot', async () => {
+    // Use bot.chat() for player commands
+    context.bot.chat('/gamemode creative');
+
+    // Use backend.sendCommand() for RCON commands
+    const result = await context.backend.sendCommand('seed');
+    expect(result.raw).toContain('Seed');
+  });
+});
+```
+
 ## StoryRunner
 
 The `StoryRunner` executes declarative test stories against Minecraft servers.
@@ -171,6 +207,84 @@ module.exports = {
 
 ## Helpers
 
+### Test Context Helper
+
+The `createTestContext()` helper provides a simplified way to create bot players for testing. It sets up both RCON and Mineflayer backends simultaneously.
+
+**Why use this?**
+
+When testing Minecraft plugins with bot players, you need TWO separate connections:
+1. **Bot player** - For executing player commands (via `bot.chat()`)
+2. **RCON** - For server commands that return responses (via `rcon.send()`)
+
+The `MineflayerBackend.sendCommand()` method only sends commands via bot chat and **always returns empty** responses. You need RCON to get actual server responses for commands like `/data get`, `/teleport`, etc.
+
+```javascript
+const { createTestContext, cleanupTestContext } = require('@pilaf/framework');
+
+describe('My Plugin', () => {
+  let context;
+
+  beforeAll(async () => {
+    context = await createTestContext({
+      username: 'TestPlayer',
+      rconPassword: 'dragon123'
+    });
+  });
+
+  afterAll(async () => {
+    await cleanupTestContext(context);
+  });
+
+  it('should verify entity position after teleport', async () => {
+    // Get position BEFORE (using RCON - returns actual data!)
+    const beforeResult = await context.rcon.send('data get entity TestPlayer Pos');
+    const beforePos = parsePosition(beforeResult);
+
+    // Execute ability (using bot chat)
+    context.bot.chat('/myplugin teleport 100 64 100');
+    await wait(1000);
+
+    // Get position AFTER (using RCON - returns actual data!)
+    const afterResult = await context.rcon.send('data get entity TestPlayer Pos');
+    const afterPos = parsePosition(afterResult);
+
+    // Verify teleportation
+    expect(afterPos.x).toBeCloseTo(100, 0);
+  });
+});
+```
+
+**API Reference:**
+
+```javascript
+const context = await createTestContext({
+  username: 'TestPlayer',      // Bot username (default: 'TestPlayer')
+  host: 'localhost',           // Server host (default: 'localhost')
+  gamePort: 25565,             // Game port (default: 25565)
+  rconPort: 25575,             // RCON port (default: 25575)
+  rconPassword: 'minecraft',   // RCON password (default: 'minecraft')
+  auth: 'offline'              // Auth mode (default: 'offline')
+});
+
+// Returns:
+{
+  backend: MineflayerBackend,  // For bot control
+  rcon: RconBackend,           // For server commands WITH RESPONSES
+  bot: Object,                 // The bot player instance
+  playerName: string          // Bot's username
+}
+
+// Use RCON for commands that need responses
+const result = await context.rcon.send('data get entity TestPlayer Pos');
+
+// Use bot chat for player commands
+context.bot.chat('/mycommand');
+
+// Cleanup when done
+await cleanupTestContext(context);
+```
+
 ### State Management
 
 ```javascript

package/lib/index.js

@@ -4,6 +4,7 @@ const { StoryRunner } = require('./StoryRunner');
 const { waitForEvents, captureEvents } = require('./helpers/events');
 const { captureState, compareStates } = require('./helpers/state');
 const { toHaveReceivedLightningStrikes } = require('./matchers/game-matchers');
+const { createTestContext, cleanupTestContext } = require('./test-context');
 
 const { PilafBackendFactory } = require('@pilaf/backends');
 
@@ -34,6 +35,10 @@ module.exports = {
   // Story Runner
   StoryRunner,
 
+  // Test Context Helper
+  createTestContext,
+  cleanupTestContext,
+
   // Main API
   pilaf,
   rcon,
@@ -46,5 +51,9 @@ module.exports = {
   compareStates,
 
   // Matchers
-  toHaveReceivedLightningStrikes
+  toHaveReceivedLightningStrikes,
+
+  // Test Context
+  createTestContext,
+  cleanupTestContext
 };

package/lib/test-context.js

@@ -0,0 +1,104 @@
+/**
+ * Test Context Helper
+ *
+ * Provides a simplified way to create bot players for testing
+ * This combines RCON and Mineflayer backends for seamless testing
+ *
+ * IMPORTANT: Returns TWO backends:
+ * - rcon: RconBackend for server commands that return responses
+ * - backend: MineflayerBackend for bot player control
+ *
+ * Use context.rcon.send() for commands like /data get, /teleport, etc.
+ * Use context.bot.chat() for player commands
+ */
+
+const { MineflayerBackend } = require('../../backends/lib/mineflayer-backend.js');
+const { RconBackend } = require('../../backends/lib/rcon-backend.js');
+
+/**
+ * Create a test context with both RCON and a bot player
+ * This is the recommended way to set up tests that need player commands
+ *
+ * @param {Object} config - Configuration
+ * @param {string} config.username - Bot username (default: 'TestPlayer')
+ * @param {string} config.host - Server host (default: 'localhost')
+ * @param {number} config.gamePort - Server game port (default: 25565)
+ * @param {number} config.rconPort - RCON port (default: 25575)
+ * @param {string} config.rconPassword - RCON password (default: 'minecraft')
+ * @param {string} config.auth - Auth mode (default: 'offline')
+ * @returns {Promise<TestContext>} Test context with rcon, backend, and bot
+ */
+async function createTestContext(config = {}) {
+  const username = config.username || 'TestPlayer';
+  const host = config.host || 'localhost';
+  const gamePort = config.gamePort || 25565;
+  const rconPort = config.rconPort || 25575;
+  const rconPassword = config.rconPassword || 'minecraft';
+  const auth = config.auth || 'offline';
+
+  // Create RCON backend for server commands (returns responses)
+  const rcon = new RconBackend();
+  await rcon.connect({
+    host,
+    port: rconPort,
+    password: rconPassword
+  });
+
+  // Create Mineflayer backend for bot players
+  const backend = new MineflayerBackend();
+
+  // Connect to server
+  await backend.connect({
+    host,
+    port: gamePort,
+    auth,
+    rconHost: host,
+    rconPort,
+    rconPassword
+  });
+
+  // Wait for server to be ready
+  await backend.waitForServerReady({ timeout: 60000 });
+
+  // Create bot player
+  const bot = await backend.createBot({
+    username,
+    auth
+  });
+
+  return { backend, rcon, bot, playerName: username };
+}
+
+/**
+ * Disconnect and cleanup test context
+ *
+ * @param {TestContext} context - The test context to cleanup
+ */
+async function cleanupTestContext(context) {
+  if (!context) return;
+
+  if (context.bot && context.backend) {
+    await context.backend.quitBot(context.bot);
+  }
+
+  if (context.backend) {
+    await context.backend.disconnect();
+  }
+
+  if (context.rcon) {
+    await context.rcon.disconnect();
+  }
+}
+
+/**
+ * @typedef {Object} TestContext
+ * @property {MineflayerBackend} backend - The Mineflayer backend instance (for bot control)
+ * @property {RconBackend} rcon - The RCON backend instance (for server commands with responses)
+ * @property {Object} bot - The bot player instance
+ * @property {string} playerName - The bot's username
+ */
+
+module.exports = {
+  createTestContext,
+  cleanupTestContext
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pilaf/framework",
-  "version": "1.0.1",
+  "version": "1.2.0",
   "main": "lib/index.js",
   "repository": {
     "type": "git",