k6lab-agent 1.0.0

package/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "k6lab-agent",
+  "version": "1.0.0",
+  "description": "Local agent for K6 Lab load testing",
+  "type": "module",
+  "bin": {
+    "k6lab-agent": "src/index.js"
+  },
+  "dependencies": {
+    "axios": "^1.6.0",
+    "commander": "^11.1.0",
+    "fs-extra": "^11.1.1"
+  }
+}

package/src/commands/login.js

@@ -0,0 +1,46 @@
+import axios from "axios";
+import { saveConfig } from "../services/configStore.js";
+
+export async function login(token) {
+  const apiUrl = process.env.K6LAB_API_URL || "http://localhost:8000";
+
+  try {
+    const res = await axios.post(
+      `${apiUrl}/api/agent/verify-token`,
+      {},
+      {
+        headers: {
+          Authorization: `Bearer ${token}`
+        },
+        timeout: 10000
+      }
+    );
+
+    await saveConfig({
+      apiUrl,
+      agentToken: token,
+      agentId: res.data.agent.id,
+      agentName: res.data.agent.name
+    });
+
+    console.log("");
+    console.log("K6 Lab Agent connected successfully.");
+    console.log("");
+    console.log(`Agent: ${res.data.agent.name}`);
+    console.log(`API: ${apiUrl}`);
+    console.log("");
+    console.log("Now start the agent:");
+    console.log("");
+    console.log("k6lab-agent start");
+    console.log("");
+  } catch (err) {
+    console.error("");
+    console.error("Agent login failed.");
+    console.error("Reason: invalid token or backend not reachable.");
+    if (err.response?.data?.error) {
+      console.error(`Details: ${err.response.data.error}`);
+    }
+    console.error("");
+    process.exit(1);
+  }
+}

package/src/commands/logout.js

@@ -0,0 +1,12 @@
+import { clearConfig } from "../services/configStore.js";
+
+export async function logout() {
+  try {
+    await clearConfig();
+    console.log("");
+    console.log("Logged out successfully. Local agent configuration wiped.");
+    console.log("");
+  } catch (err) {
+    console.error("Logout action failed:", err.message);
+  }
+}

package/src/commands/start.js

@@ -0,0 +1,173 @@
+import fs from "fs-extra";
+import { checkK6Installed } from "../services/k6Checker.js";
+import {
+  sendHeartbeat,
+  getNextJob,
+  uploadResult,
+  uploadLogs,
+  failJob,
+  cancelJob,
+  getJobStatus
+} from "../services/api.js";
+import { createK6Script } from "../services/scriptGenerator.js";
+import { runK6, stopCurrentK6Process } from "../services/runner.js";
+import { sleep } from "../utils/sleep.js";
+
+let isShuttingDown = false;
+
+process.on("SIGINT", async () => {
+  console.log("");
+  console.log("Stopping K6 Lab Agent...");
+
+  isShuttingDown = true;
+  stopCurrentK6Process();
+
+  console.log("Agent stopped.");
+  process.exit(0);
+});
+
+export async function start() {
+  console.log("");
+  console.log("Starting K6 Lab Agent...");
+  console.log("");
+
+  try {
+    console.log("Checking k6 installation...");
+    await checkK6Installed();
+
+    console.log("k6 is installed and ready.");
+    console.log("");
+    console.log("Connected to K6 Lab dashboard.");
+    console.log("Agent is online.");
+    console.log("");
+    console.log("You can now create a test from your dashboard.");
+    console.log("Waiting for jobs...");
+    console.log("");
+
+    while (!isShuttingDown) {
+      try {
+        await sendHeartbeat();
+
+        const job = await getNextJob();
+
+        if (!job) {
+          await sleep(3000);
+          continue;
+        }
+
+        console.log("");
+        console.log(`New test received: ${job.name || job.id}`);
+        console.log("");
+        console.log(`${job.config.method} ${job.config.url}`);
+        console.log(`VUs: ${job.config.vus}`);
+        console.log(`Duration: ${job.config.duration}`);
+        console.log("");
+        console.log("Running k6 locally...");
+        console.log("Please keep this terminal open.");
+        console.log("You can monitor progress in your K6 Lab dashboard.");
+        console.log("");
+
+        let cancelCheckInterval = null;
+        let localCancelled = false;
+
+        // 🔹 Background dashboard cancellation monitor
+        cancelCheckInterval = setInterval(async () => {
+          try {
+            const statusData = await getJobStatus(job.id);
+            if (statusData && statusData.status === "cancel_requested") {
+              console.log("");
+              console.log("--> Cancellation requested from dashboard. Aborting run...");
+              localCancelled = true;
+              stopCurrentK6Process();
+              clearInterval(cancelCheckInterval);
+            }
+          } catch (err) {
+            // Ignore status polling errors
+          }
+        }, 2000);
+
+        try {
+          const { scriptPath, summaryPath, logsPath } = await createK6Script(job);
+
+          const runResult = await runK6(scriptPath, job, logsPath);
+
+          if (cancelCheckInterval) clearInterval(cancelCheckInterval);
+
+          let summary = null;
+          if (await fs.pathExists(summaryPath)) {
+            summary = await fs.readJson(summaryPath);
+          }
+
+          await uploadLogs(job.id, runResult.logs);
+
+          await uploadResult(job.id, {
+            status: "completed",
+            summary,
+            logs: runResult.logs
+          });
+
+          console.log("");
+          console.log("Test completed successfully.");
+          console.log("");
+          console.log("Results uploaded to your K6 Lab dashboard.");
+          console.log("Open the dashboard to view the full performance report.");
+          console.log("");
+          console.log("Waiting for jobs...");
+          console.log("");
+        } catch (err) {
+          if (cancelCheckInterval) clearInterval(cancelCheckInterval);
+
+          if (localCancelled) {
+            await cancelJob(job.id, "Test cancelled by user from dashboard");
+            console.log("");
+            console.log("Test execution successfully cancelled.");
+            console.log("");
+          } else {
+            // Check if backend cancellation requested in middle of execution
+            try {
+              const currentStatus = await getJobStatus(job.id);
+              if (currentStatus && (currentStatus.status === "cancel_requested" || currentStatus.status === "cancelled")) {
+                await cancelJob(job.id, "Test cancelled by user from dashboard");
+                console.log("");
+                console.log("Test execution successfully cancelled.");
+                console.log("");
+                console.log("Waiting for jobs...");
+                console.log("");
+                continue;
+              }
+            } catch (statusErr) {
+              // fallback to failure
+            }
+
+            await failJob(job.id, err.message);
+
+            console.log("");
+            console.log("Test failed.");
+            console.log("");
+            console.log("Reason:");
+            console.log(err.message);
+            console.log("");
+            console.log("The failure details were uploaded to your dashboard.");
+            console.log("Please check your local API and try again.");
+            console.log("");
+          }
+
+          console.log("Waiting for jobs...");
+          console.log("");
+        }
+      } catch (err) {
+        console.error("Agent connection error:", err.message);
+        await sleep(5000);
+      }
+    }
+  } catch (err) {
+    console.error("");
+    console.error(err.message);
+    console.error("");
+    console.error("Fix the issue and run:");
+    console.error("");
+    console.error("k6lab-agent start");
+    console.error("");
+    process.exit(1);
+  }
+}

package/src/commands/status.js

@@ -0,0 +1,19 @@
+import { getConfig } from "../services/configStore.js";
+
+export async function status() {
+  try {
+    const config = await getConfig();
+    console.log("");
+    console.log("K6 Lab Agent Status: Connected");
+    console.log("------------------------------");
+    console.log(`Agent Name:  ${config.agentName}`);
+    console.log(`Agent ID:    ${config.agentId}`);
+    console.log(`API URL:     ${config.apiUrl}`);
+    console.log("");
+  } catch (err) {
+    console.log("");
+    console.log("K6 Lab Agent Status: Disconnected / Not Logged In");
+    console.log("Run: k6lab-agent login <token> to connect your local environment.");
+    console.log("");
+  }
+}

package/src/index.js

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+
+import { Command } from "commander";
+import { login } from "./commands/login.js";
+import { start } from "./commands/start.js";
+import { status } from "./commands/status.js";
+import { logout } from "./commands/logout.js";
+
+const program = new Command();
+
+program
+  .name("k6lab-agent")
+  .description("Local agent for K6 Lab")
+  .version("1.0.0");
+
+program
+  .command("login")
+  .description("Login with your K6 Lab agent token")
+  .argument("<token>", "Agent token from K6 Lab dashboard")
+  .action(login);
+
+program
+  .command("start")
+  .description("Start agent and wait for dashboard jobs")
+  .action(start);
+
+program
+  .command("status")
+  .description("Show local agent login status")
+  .action(status);
+
+program
+  .command("logout")
+  .description("Remove local agent token")
+  .action(logout);
+
+program.parse();

package/src/services/api.js

@@ -0,0 +1,62 @@
+import axios from "axios";
+import { getConfig } from "./configStore.js";
+
+async function createClient() {
+  const config = await getConfig();
+
+  return axios.create({
+    baseURL: config.apiUrl,
+    headers: {
+      Authorization: `Bearer ${config.agentToken}`
+    },
+    timeout: 10000
+  });
+}
+
+export async function sendHeartbeat() {
+  const api = await createClient();
+  const res = await api.post("/api/agent/heartbeat");
+  return res.data;
+}
+
+export async function getNextJob() {
+  const api = await createClient();
+  const res = await api.get("/api/agent/jobs/next");
+  return res.data.job;
+}
+
+export async function getJobStatus(jobId) {
+  const api = await createClient();
+  const res = await api.get(`/api/agent/jobs/${jobId}/status`);
+  return res.data.job;
+}
+
+export async function uploadLogs(jobId, logs) {
+  const api = await createClient();
+  const res = await api.post(`/api/agent/jobs/${jobId}/logs`, {
+    logs
+  });
+  return res.data;
+}
+
+export async function uploadResult(jobId, payload) {
+  const api = await createClient();
+  const res = await api.post(`/api/agent/jobs/${jobId}/result`, payload);
+  return res.data;
+}
+
+export async function failJob(jobId, error) {
+  const api = await createClient();
+  const res = await api.post(`/api/agent/jobs/${jobId}/fail`, {
+    error
+  });
+  return res.data;
+}
+
+export async function cancelJob(jobId, message) {
+  const api = await createClient();
+  const res = await api.post(`/api/agent/jobs/${jobId}/cancelled`, {
+    message
+  });
+  return res.data;
+}

package/src/services/configStore.js

@@ -0,0 +1,29 @@
+import fs from "fs-extra";
+import os from "os";
+import path from "path";
+
+const configDir = path.join(os.homedir(), ".k6lab");
+const configPath = path.join(configDir, "config.json");
+
+export async function saveConfig(config) {
+  await fs.ensureDir(configDir);
+  await fs.writeJson(configPath, config, { spaces: 2 });
+}
+
+export async function getConfig() {
+  const exists = await fs.pathExists(configPath);
+
+  if (!exists) {
+    throw new Error("Agent is not logged in. Run: k6lab-agent login <token>");
+  }
+
+  return fs.readJson(configPath);
+}
+
+export async function clearConfig() {
+  await fs.remove(configPath);
+}
+
+export function getK6LabDir() {
+  return configDir;
+}

package/src/services/k6Checker.js

@@ -0,0 +1,25 @@
+import { spawn } from "child_process";
+
+export function checkK6Installed() {
+  return new Promise((resolve, reject) => {
+    const child = spawn("k6", ["version"], {
+      shell: false
+    });
+
+    child.on("error", () => {
+      reject(
+        new Error(
+          "k6 is not installed. Please install k6 first, then run the agent again."
+        )
+      );
+    });
+
+    child.on("close", (code) => {
+      if (code === 0) {
+        resolve(true);
+      } else {
+        reject(new Error("k6 is installed but not working correctly."));
+      }
+    });
+  });
+}

package/src/services/runner.js

@@ -0,0 +1,73 @@
+import { spawn } from "child_process";
+import fs from "fs-extra";
+
+let currentProcess = null;
+
+export function stopCurrentK6Process() {
+  if (currentProcess) {
+    currentProcess.kill("SIGTERM");
+  }
+}
+
+export function runK6(scriptPath, job, logsPath) {
+  return new Promise((resolve, reject) => {
+    currentProcess = spawn("k6", ["run", scriptPath], {
+      shell: false,
+      env: {
+        ...process.env,
+
+        K6LAB_URL: job.config.url,
+        K6LAB_METHOD: job.config.method,
+        K6LAB_VUS: String(job.config.vus),
+        K6LAB_DURATION: job.config.duration,
+
+        K6LAB_HEADERS: JSON.stringify(job.config.headers || {}),
+        K6LAB_BODY:
+          job.config.body === null || job.config.body === undefined
+            ? ""
+            : typeof job.config.body === "string"
+              ? job.config.body
+              : JSON.stringify(job.config.body),
+
+        K6LAB_EXPECTED_STATUS: String(job.config.expectedStatus || 200),
+        K6LAB_MAX_RESPONSE_TIME_MS: String(job.config.maxResponseTimeMs || 1000),
+        K6LAB_SLEEP_SECONDS: String(job.config.sleepSeconds ?? 1),
+        K6LAB_TIMEOUT: job.config.timeout || "30s"
+      }
+    });
+
+    let stdout = "";
+    let stderr = "";
+
+    currentProcess.stdout.on("data", async (data) => {
+      const text = data.toString();
+      stdout += text;
+      await fs.appendFile(logsPath, text);
+    });
+
+    currentProcess.stderr.on("data", async (data) => {
+      const text = data.toString();
+      stderr += text;
+      await fs.appendFile(logsPath, text);
+    });
+
+    currentProcess.on("error", (err) => {
+      currentProcess = null;
+      reject(err);
+    });
+
+    currentProcess.on("close", (code) => {
+      currentProcess = null;
+
+      if (code === 0) {
+        resolve({
+          stdout,
+          stderr,
+          logs: stdout + stderr
+        });
+      } else {
+        reject(new Error(`k6 exited with code ${code}\n${stderr || stdout}`));
+      }
+    });
+  });
+}

package/src/services/scriptGenerator.js

@@ -0,0 +1,82 @@
+import fs from "fs-extra";
+import os from "os";
+import path from "path";
+
+export async function createK6Script(job) {
+  const jobDir = path.join(os.homedir(), ".k6lab", "jobs", job.id);
+
+  await fs.ensureDir(jobDir);
+
+  const scriptPath = path.join(jobDir, "script.js");
+  const summaryPath = path.join(jobDir, "summary.json");
+  const logsPath = path.join(jobDir, "logs.txt");
+  const metadataPath = path.join(jobDir, "metadata.json");
+
+  await fs.writeJson(
+    metadataPath,
+    {
+      jobId: job.id,
+      name: job.name,
+      config: job.config,
+      createdAt: new Date().toISOString()
+    },
+    { spaces: 2 }
+  );
+
+  const escapedSummaryPath = summaryPath.replaceAll("\\", "\\\\");
+
+  const script = `
+import http from "k6/http";
+import { check, sleep } from "k6";
+
+export const options = {
+  vus: Number(__ENV.K6LAB_VUS || 1),
+  duration: __ENV.K6LAB_DURATION || "10s",
+};
+
+export default function () {
+  const method = __ENV.K6LAB_METHOD || "GET";
+  const url = __ENV.K6LAB_URL;
+
+  const headers = JSON.parse(__ENV.K6LAB_HEADERS || "{}");
+  const body = __ENV.K6LAB_BODY || null;
+
+  const params = {
+    headers,
+    timeout: __ENV.K6LAB_TIMEOUT || "30s"
+  };
+
+  const res = http.request(method, url, body, params);
+
+  check(res, {
+    "status is expected": (r) => {
+      const expectedStatus = Number(__ENV.K6LAB_EXPECTED_STATUS || 200);
+      return r.status === expectedStatus;
+    },
+    "response time is acceptable": (r) => {
+      const maxMs = Number(__ENV.K6LAB_MAX_RESPONSE_TIME_MS || 1000);
+      return r.timings.duration < maxMs;
+    }
+  });
+
+  const sleepSeconds = Number(__ENV.K6LAB_SLEEP_SECONDS || 1);
+  sleep(sleepSeconds);
+}
+
+export function handleSummary(data) {
+  return {
+    "${escapedSummaryPath}": JSON.stringify(data)
+  };
+}
+`.trim();
+
+  await fs.writeFile(scriptPath, script, "utf8");
+
+  return {
+    jobDir,
+    scriptPath,
+    summaryPath,
+    logsPath,
+    metadataPath
+  };
+}

package/src/utils/sleep.js

@@ -0,0 +1 @@
+export const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));