zach/dotter

// End-to-end safety tests: the real driver against the simulated machine.

// The simulator flags anything that would hurt real hardware (driving the

// carriage past its travel, step rates beyond the firmware limit, motion

// after a limit stop, malformed commands), so every test asserts that

// sim.violations is empty in addition to its own checks.

import { describe, expect, test } from 'bun:test';

import { commands, connected, makeMachine, polylineSetDistance, rng } from './helpers.js';

const TRAVEL = [11.81, 8.58];

const ONE_STEP = 1 / 2032;

function expectSafe(sim) {

  expect(sim.violations).toEqual([]);

}

/** Carriage is at (x, y) within ~1 step, and the driver's tracked position is exact. */

function expectAt(nd, sim, x, y) {

  expect(Math.abs(sim.position[0] - x)).toBeLessThan(0.0015);

  expect(Math.abs(sim.position[1] - y)).toBeLessThan(0.0015);

  expectTracked(nd, sim);

}

function expectTracked(nd, sim) {

  expect(Math.abs(nd.pen.phys.xpos - sim.position[0])).toBeLessThan(1e-9);

  expect(Math.abs(nd.pen.phys.ypos - sim.position[1])).toBeLessThan(1e-9);

}

describe('automatic homing', () => {

  const starts = [[0, 0], [5, 4], [11.8, 8.5], [0, 8.5], [11.8, 0], [0.05, 0.05], [3, 0], [0, 3], [7.3, 1.1], [0.2, 6]];

  for (const [x, y] of starts) {

    test(`homes from (${x}, ${y})`, async () => {

      const { nd, sim } = await connected({ startX: x, startY: y });

      expectSafe(sim);

      expect(Math.abs(sim.position[0])).toBeLessThan(2 * ONE_STEP);

      expect(Math.abs(sim.position[1])).toBeLessThan(2 * ONE_STEP);

      expect(nd.currentPos()).toEqual([0, 0]);

      expect(sim.vars[12]).toBe(1); // EBB marked homed

      expect(sim.penUp).toBe(true);

      expect(sim.ink).toEqual([]); // Pen stayed up the whole time

    });

  }

  test('fails safely with no limit switch', async () => {

    const { nd, sim } = makeMachine({ startX: 4, startY: 4, limitSwitch: false });

    expect(await nd.connect()).toBe(false);

    expect(nd.plotStatus.stopped).toBe(106);

    expect(sim.vars[12]).toBe(0);

    expectSafe(sim);

  });

  test('fails safely without motor power, without moving', async () => {

    const { nd, sim } = makeMachine({ startX: 4, startY: 4, powered: false });

    expect(await nd.connect()).toBe(false);

    expect(nd.plotStatus.stopped).toBe(105);

    expect(sim.position).toEqual([4, 4]);

    expectSafe(sim);

  });

  test('errors.homing = true throws', async () => {

    const { nd } = makeMachine({ startX: 4, startY: 4, limitSwitch: false });

    nd.errors.homing = true;

    await expect(nd.connect()).rejects.toThrow('Homing failed');

  });

});

describe('interactive motion', () => {

  test('square with moveto/lineto draws exactly the square', async () => {

    const { nd, sim } = await connected({ startX: 2, startY: 2 });

    await nd.moveto(1, 1);

    await nd.lineto(3, 1);

    await nd.lineto(3, 2.5);

    await nd.lineto(1, 2.5);

    await nd.lineto(1, 1);

    await nd.penup();

    await nd.moveto(0, 0);

    await nd.disconnect();

    expectSafe(sim);

    expect(sim.ink.length).toBe(1);

    expect(polylineSetDistance(sim.ink, [[[1, 1], [3, 1], [3, 2.5], [1, 2.5], [1, 1]]])).toBeLessThan(0.002);

    expectAt(nd, sim, 0, 0);

  });

  test('relative moves and pen state queries', async () => {

    const { nd, sim } = await connected();

    await nd.move(2, 1);

    expect(nd.turtlePos()).toEqual([2, 1]);

    expect(nd.currentPen()).toBe(true);

    await nd.line(1, 0);

    expect(nd.currentPen()).toBe(false);

    await nd.go(0, 1);

    await nd.penup();

    expect(nd.turtlePen()).toBe(true);

    expectSafe(sim);

    expect(polylineSetDistance(sim.ink, [[[2, 1], [3, 1], [3, 2]]])).toBeLessThan(0.002);

    expectAt(nd, sim, 3, 2);

  });

  test('pen-up moves never leave ink', async () => {

    const { nd, sim } = await connected();

    const rand = rng(3);

    for (let i = 0; i < 40; i++) await nd.moveto(rand() * 11, rand() * 8);

    expectSafe(sim);

    expect(sim.ink).toEqual([]);

  });

  test('units: millimeters and centimeters', async () => {

    const { nd, sim } = await connected();

    nd.options.units = 2;

    await nd.moveto(25.4, 50.8);

    expectAt(nd, sim, 1, 2);

    expect(nd.currentPos()[0]).toBeCloseTo(25.4, 1);

    nd.options.units = 1;

    await nd.moveto(5.08, 2.54);

    expectAt(nd, sim, 2, 1);

    expectSafe(sim);

  });

  test('targets outside the travel area are clipped, with the pen lifted outside', async () => {

    const { nd, sim } = await connected();

    await nd.moveto(-3, -3);

    expectAt(nd, sim, 0, 0);

    await nd.lineto(20, 4); // Crosses the right edge

    await nd.lineto(5, 20); // Entirely outside -> no motion

    await nd.lineto(5, 4); // Back inside from outside

    await nd.penup();

    expectSafe(sim);

    // Ink: (0,0)->(11.81, 2.4)ish clipped segment, then re-entry segment into (5,4)

    for (const line of sim.ink) {

      for (const [x, y] of line) {

        expect(x).toBeGreaterThanOrEqual(-ONE_STEP);

        expect(x).toBeLessThanOrEqual(TRAVEL[0] + ONE_STEP);

        expect(y).toBeGreaterThanOrEqual(-ONE_STEP);

        expect(y).toBeLessThanOrEqual(TRAVEL[1] + ONE_STEP);

      }

    }

    expect(nd.turtlePos()).toEqual([5, 4]);

    expectAt(nd, sim, 5, 4);

  });

  test('pendown outside the travel area does not lower the pen', async () => {

    const { nd, sim } = await connected();

    await nd.moveto(-1, 2);

    await nd.pendown();

    expect(sim.penUp).toBe(true);

    expectSafe(sim);

  });

  test('random stress session stays in bounds and in sync', async () => {

    const { nd, sim } = await connected({ startX: 6, startY: 3 });

    const rand = rng(2024);

    const ops = ['moveto', 'lineto', 'goto', 'move', 'line', 'go', 'penup', 'pendown'];

    for (let i = 0; i < 150; i++) {

      const op = ops[Math.floor(rand() * ops.length)];

      if (op === 'penup' || op === 'pendown') {

        await nd[op]();

      } else if (['move', 'line', 'go'].includes(op)) {

        await nd[op]((rand() - 0.5) * 6, (rand() - 0.5) * 6);

      } else {

        await nd[op](rand() * 15 - 2, rand() * 12 - 2);

      }

      expectTracked(nd, sim);

    }

    expectSafe(sim);

  });

  test('delay is sent as hardware SM pauses of at most 750 ms', async () => {

    const { nd, sim } = await connected();

    const n = sim.log.length;

    await nd.delay(2000);

    expect(sim.log.slice(n).map((l) => l.cmd)).toEqual(['SM,750,0,0', 'SM,750,0,0', 'SM,500,0,0']);

  });

  test('walkHome returns to the origin', async () => {

    const { nd, sim } = await connected();

    await nd.moveto(7, 5);

    await nd.walkHome();

    expectSafe(sim);

    expectAt(nd, sim, 0, 0);

  });

  test('update() applies new pen heights to the servo', async () => {

    const { nd, sim } = await connected();

    nd.options.penPosDown = 20;

    await nd.update();

    expect(sim.servoMax).toBe(5400 + 72 * 20);

    expectSafe(sim);

  });

  test('changing handling mode mid-session re-homes and stays in sync', async () => {

    const { nd, sim } = await connected();

    await nd.moveto(4, 3);

    nd.options.handling = 2; // high-res -> low-res motors

    await nd.update();

    expect(sim.vars[12]).toBe(1);

    expectAt(nd, sim, 0, 0);

    await nd.moveto(5, 2);

    await nd.lineto(6, 2);

    await nd.walkHome();

    expectAt(nd, sim, 0, 0);

    expectSafe(sim);

  });

  test('raw usbQuery / usbCommand', async () => {

    const { nd } = await connected();

    expect(await nd.usbQuery('QS')).toBe('0,0');

    await nd.usbCommand('SL,7,3');

    expect(await nd.usbQuery('QL,3')).toBe('7');

  });

});

describe('drawPath', () => {

  test('circle is drawn within tolerance', async () => {

    const { nd, sim } = await connected();

    const circle = [];

    for (let i = 0; i <= 120; i++) {

      const a = (i / 120) * 2 * Math.PI;

      circle.push([4 + 2 * Math.cos(a), 4 + 2 * Math.sin(a)]);

    }

    await nd.drawPath(circle);

    expectSafe(sim);

    expect(sim.penUp).toBe(true);

    expect(polylineSetDistance(sim.ink, [circle])).toBeLessThan(0.003);

  });

  test('a path leaving the travel area is split, not driven past the edge', async () => {

    const { nd, sim } = await connected();

    const path = [[10, 2], [14, 2], [14, 4], [10, 4]];

    await nd.drawPath(path);

    expectSafe(sim);

    expect(sim.ink.length).toBe(2);

    expect(polylineSetDistance(sim.ink, [[[10, 2], [TRAVEL[0], 2]], [[TRAVEL[0], 4], [10, 4]]])).toBeLessThan(0.002);

  });

  test('millimeter units', async () => {

    const { nd, sim } = await connected();

    nd.options.units = 2;

    await nd.drawPath([[10, 10], [60, 10], [60, 40]]);

    expectSafe(sim);

    const expected = [[[10, 10], [60, 10], [60, 40]].map(([x, y]) => [x / 25.4, y / 25.4])];

    expect(polylineSetDistance(sim.ink, expected)).toBeLessThan(0.002);

  });

});

describe('speed limits (measured from step rates)', () => {

  for (const handling of [1, 2, 3, 4]) {

    for (const [down, up] of [[25, 75], [100, 100], [5, 10]]) {

      test(`handling ${handling}, speed ${down}/${up}`, async () => {

        const { nd, sim } = await connected({}, (n) => {

          n.options.handling = handling;

          n.options.speedPendown = down;

          n.options.speedPenup = up;

        });

        sim.stats.peakSpeedUp = 0; // Ignore the homing routine's own moves.

        await nd.drawPath([[0.5, 0.5], [11, 0.5], [11, 8], [0.5, 8], [6, 4], [6.01, 4.2], [0.5, 0.5]]);

        await nd.moveto(11, 8);

        await nd.moveto(0.2, 0.3);

        expectSafe(sim);

        // Pen-down: never faster than the configured pen-down speed.

        expect(sim.stats.peakSpeedDown).toBeLessThanOrEqual(nd.speedPendown * 1.01);

        // Pen-up: never faster than the configured pen-up speed.

        expect(sim.stats.peakSpeedUp).toBeLessThanOrEqual(nd.speedPenup * 1.01);

        // Firmware hard limit: < 1 step per 40 µs tick on each motor.

        expect(sim.stats.maxRate).toBeLessThan(2147483648);

        expect(polylineSetDistance(sim.ink,

          [[[0.5, 0.5], [11, 0.5], [11, 8], [0.5, 8], [6, 4], [6.01, 4.2], [0.5, 0.5]]])).toBeLessThan(0.003);

      });

    }

  }

});

describe('stopping a plot', () => {

  const square = (o) => [[o, o], [o + 3, o], [o + 3, o + 3], [o, o + 3], [o, o]];

  const job = [square(1), square(2), square(3), square(4)];

  function interruptAfter(sim, count, action) {

    const orig = sim.handle.bind(sim);

    let n = 0;

    sim.handle = (cmd) => {

      orig(cmd);

      if (/^(T3|TD)/.test(cmd) && ++n === count) action();

    };

  }

  test('a full plot draws everything and returns home', async () => {

    const { nd, sim } = await connected();

    const result = await nd.plotPolylines(job);

    expect(result.stopped).toBe(0);

    expectSafe(sim);

    expect(polylineSetDistance(sim.ink, job)).toBeLessThan(0.002);

    expectAt(nd, sim, 0, 0);

  });

  test('software stop request raises the pen and stops', async () => {

    const { nd, sim } = await connected();

    interruptAfter(sim, 30, () => nd.requestPause());

    const result = await nd.plotPolylines(job);

    expect(result.stopped).toBe(103);

    expect(sim.penUp).toBe(true);

    expect(commands(sim)).toContain('SP,3');

    expectSafe(sim);

    // Still usable afterwards.

    await nd.moveto(0, 0);

    expectAt(nd, sim, 0, 0);

    expectSafe(sim);

  });

  test('PRG button press stops the plot', async () => {

    const { nd, sim } = await connected();

    interruptAfter(sim, 20, () => sim.pressButton());

    const result = await nd.plotPolylines(job);

    expect(result.stopped).toBe(102);

    expect(sim.penUp).toBe(true);

    expectSafe(sim);

  });

  test('power loss stops the plot and marks the machine un-homed', async () => {

    const { nd, sim } = await connected();

    interruptAfter(sim, 20, () => sim.setPower(false));

    const result = await nd.plotPolylines(job);

    expect(result.stopped).toBe(105);

    expect(sim.vars[12]).toBe(0);

    expectSafe(sim);

  });

  test('a move beyond the firmware step-rate limit is refused, pen raised', async () => {

    const { nd, sim } = await connected();

    const { feed } = await import('../src/control.js');

    await nd.pen.lower(nd);

    const pos = { ...nd.pen.phys };

    await feed(nd, [['T3', [100, 2147483647, 1000, 0, 0, 0, 0], [0.1, pos]]]);

    expect(nd.plotStatus.stopped).toBe(107);

    expect(sim.penUp).toBe(true);

    expect(commands(sim).some((c) => c.startsWith('T3,100'))).toBe(false);

    expectSafe(sim);

  });

  test('USB unplug mid-plot stops without hanging', async () => {

    const { nd, sim } = await connected();

    interruptAfter(sim, 20, () => sim.unplug());

    const result = await nd.plotPolylines(job);

    expect(result.stopped).toBe(104);

    expectSafe(sim);

  });

});