Testing

When developing a plugin for Automation, you can run and test it locally without needing the full Automation stack.

This page explains how to simulate Automation in development mode using the automation-dev CLI.

---

🧪 Local Plugin Testing

You can use the command below to run your plugin in isolation:

automation-dev run path/to/your-plugin-directory

This will:

• Load your automation.json
• Pass a simulated Context object to your start() function
• Auto-reload on file changes
• Store all data in a local PouchDB directory

---

🧰 Project Structure

Your plugin folder must include:

• automation.json — Plugin definition
• Compiled JS file — The plugin’s entrypoint (from automation.json.entrypoint)

If you're writing in TypeScript, compile your code to JavaScript first:

src/
  index.ts
dist/
  index.js
automation.json → { "entrypoint": "dist/index.js" }

The dev runner will automatically re-run your plugin whenever the entrypoint file changes.

---

🧪 Simulating Inputs

You can send test resources to your plugin using CLI flags:

automation-dev run ./plugins/dhis2-reporter \
  --simulate DiagnosticReport=./test/cbc.json

This injects the file into your plugin via context.on("DiagnosticReport", ...).

---

🛠 Context Simulation

The dev runner fakes a connection with:

• A mock connection object matching your plugin type
• A temporary PouchDB instance for all data
• Fully typed context.on, context.produce, context.status

No sync routing or external plugins are used — just your logic.

---

📤 Debug Output

You'll see:

[plugin] Starting plugin: dhis2-reporter
[status] connected
[on:DiagnosticReport] Received report 2301
[status] synced: XYZ-DATA-045

Use console.log() or context.status() for debug messages.

---

🔁 Live Reload

As long as your compiled file changes, the runner will auto-restart.

Recommended tsconfig.json:

{
  "compilerOptions": {
    "target": "es2020",
    "outDir": "dist",
    "module": "commonjs",
    "esModuleInterop": true,
    "moduleResolution": "node",
    "skipLibCheck": true
  },
  "include": ["src"]
}

Then run:

tsc --watch

The plugin will reload automatically on changes to dist/index.js.

---

🧼 Cleanup

To reset everything:

rm -rf .automation-dev-db

Or use a custom database path:

automation-dev run ./my-plugin --db ./dev-db

---

✅ Recap

Feature	Supported
Hot reload on save	✅
Simulated resources	✅
Console logging	✅
PouchDB persistence	✅
Resource delivery	✅
Sync tracking	✅

---

Next: Writing Device Plugins →

Would you like a `package.json` example for plugins or the dev runner too?