test: fix MutexState edge-case assertions and add lockfile

Author: leiding01

meetingnotes.md

@@ -3,6 +3,9 @@
   "private": true,
   "type": "module",
   "scripts": {
-    "test": "node tools/smoke_tests.mjs"
+    "test:smoke": "node tools/smoke_tests.mjs",
+    "test:unit": "node --test tests/*.test.mjs",
+    "test:coverage": "node --test --experimental-test-coverage tests/*.test.mjs",
+    "test": "npm run test:smoke && npm run test:unit"
   }
-}
+}

package.json

@@ -0,0 +1,68 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import * as core from '../mutex_core.js';
+import { lastTrace } from './helpers.mjs';
+
+test('clampInt clamps and defaults correctly', () => {
+  assert.equal(core.clampInt(5.9, 2, 8), 5);
+  assert.equal(core.clampInt(-1, 2, 8), 2);
+  assert.equal(core.clampInt(99, 2, 8), 8);
+  assert.equal(core.clampInt('not-a-number', 2, 8), 2);
+});
+
+test('makeModel, getProc, anyInCS, alivePids, ringNextAlive basics', () => {
+  const tr = core.makeModel(4, 'TokenRing');
+  assert.equal(tr.algorithm, 'TokenRing');
+  assert.equal(core.getProc(tr, 'P1').id, 'P1');
+  assert.equal(core.anyInCS(tr), null);
+  assert.deepEqual(core.alivePids(tr), ['P1', 'P2', 'P3', 'P4']);
+  assert.equal(core.ringNextAlive(tr, 'P1'), 'P2');
+
+  core.crashProcess(tr, 'P2');
+  assert.deepEqual(core.alivePids(tr), ['P1', 'P3', 'P4']);
+  assert.equal(core.ringNextAlive(tr, 'P1'), 'P3');
+
+  const ra = core.makeModel(3, 'RA');
+  assert.equal(ra.algorithm, 'RA');
+});
+
+test('checkSafety detects >1 process in CS', () => {
+  const model = core.makeModel(3, 'RA');
+  core.getProc(model, 'P1').inCS = true;
+  core.getProc(model, 'P2').inCS = true;
+  const safety = core.checkSafety(model);
+  assert.equal(safety.ok, false);
+  assert.match(safety.message, />1 process/);
+});
+
+test('public actions reject unsupported / not interactive cases', () => {
+  const tr = core.makeModel(3, 'TokenRing');
+  tr.mode = 'script';
+  assert.equal(core.requestCS(tr, 'P1').ok, false);
+  assert.equal(core.releaseCS(tr, 'P1').ok, false);
+  assert.equal(core.dropToken(tr).ok, false);
+  assert.equal(core.regenerateToken(tr).ok, false);
+  assert.equal(core.crashProcess(tr, 'P1').ok, false);
+  assert.equal(core.recoverProcess(tr, 'P1').ok, false);
+
+  const ra = core.makeModel(3, 'RA');
+  assert.equal(core.dropToken(ra).reason, 'unsupported_algorithm');
+  assert.equal(core.regenerateToken(ra).reason, 'unsupported_algorithm');
+  assert.equal(core.dropNextMessage(core.makeModel(3, 'TokenRing')).reason, 'unsupported_algorithm');
+  assert.equal(core.toggleDropNextSend(core.makeModel(3, 'TokenRing')).reason, 'unsupported_algorithm');
+});
+
+test('stepOnce reports unsupported algorithm paths', () => {
+  const model = core.makeModel(3, 'RA');
+  model.algorithm = 'Bogus';
+  const res = core.stepOnce(model);
+  assert.equal(res.reason, 'unsupported_algorithm');
+  assert.match(lastTrace(model), /Unsupported algorithm/);
+
+  model.mode = 'script';
+  model.script.events = [{ t: 0, op: 'noop' }];
+  model.script.index = 0;
+  const res2 = core.stepOnce(model);
+  assert.equal(res2.reason, 'unsupported_algorithm');
+  assert.match(lastTrace(model), /Unsupported algorithm in script/);
+});

report/Automated_Test_Report.pdf

@@ -0,0 +1,103 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import * as core from '../mutex_core.js';
+import { stepN, stepUntil, lastTrace, assertSafety, inCS } from './helpers.mjs';
+
+test('TokenRing basic request / entry / release / pass', () => {
+  const model = core.makeModel(4, 'TokenRing');
+
+  assert.equal(core.requestCS(model, 'P1').ok, true);
+  stepUntil(core, model, () => inCS(core, model, 'P1'), 50, 'P1 enters');
+  assertSafety(core, model);
+
+  assert.equal(core.requestCS(model, 'P2').ok, true);
+  stepN(core, model, 3);
+  assert.equal(inCS(core, model, 'P1'), true);
+  assert.equal(inCS(core, model, 'P2'), false);
+  assert.match(lastTrace(model), /release required/);
+
+  assert.equal(core.releaseCS(model, 'P1').ok, true);
+  stepUntil(core, model, () => inCS(core, model, 'P2'), 100, 'P2 enters');
+  assertSafety(core, model);
+});
+
+test('TokenRing invalid request / release cases', () => {
+  const model = core.makeModel(3, 'TokenRing');
+  assert.equal(core.requestCS(model, 'P9').reason, 'unknown_process');
+  assert.equal(core.releaseCS(model, 'P1').reason, 'not_in_cs');
+
+  assert.equal(core.requestCS(model, 'P1').ok, true);
+  assert.equal(core.requestCS(model, 'P1').reason, 'already_requesting');
+
+  stepUntil(core, model, () => inCS(core, model, 'P1'), 20, 'P1 enters');
+  assert.equal(core.requestCS(model, 'P1').reason, 'already_in_cs');
+
+  core.crashProcess(model, 'P2');
+  assert.equal(core.requestCS(model, 'P2').reason, 'crashed');
+});
+
+test('TokenRing token loss and regeneration', () => {
+  const model = core.makeModel(4, 'TokenRing');
+
+  assert.equal(core.dropToken(model).ok, true);
+  assert.equal(model.token.lost, true);
+
+  assert.equal(core.requestCS(model, 'P1').ok, true);
+  stepN(core, model, 2);
+  assert.equal(inCS(core, model, 'P1'), false);
+  assert.match(lastTrace(model), /token is lost/);
+
+  assert.equal(core.regenerateToken(model).ok, true);
+  stepUntil(core, model, () => inCS(core, model, 'P1'), 20, 'P1 enters after regen');
+});
+
+test('TokenRing crash / recover edge cases', () => {
+  const model = core.makeModel(3, 'TokenRing');
+
+  assert.equal(model.token.holder, 'P1');
+  assert.equal(core.crashProcess(model, 'P1').ok, true);
+  assert.equal(model.token.lost, true);
+  assert.equal(core.crashProcess(model, 'P1').reason, 'already_crashed');
+
+  assert.equal(core.recoverProcess(model, 'P1').ok, true);
+  assert.equal(core.recoverProcess(model, 'P1').reason, 'not_crashed');
+
+  assert.equal(core.regenerateToken(model).ok, true);
+
+  core.requestCS(model, 'P1');
+  stepUntil(core, model, () => inCS(core, model, 'P1'), 20, 'P1 enters');
+
+  core.crashProcess(model, 'P1');
+  const r = core.stepOnce(model);
+  assert.equal(r.reason, 'token_lost');
+  assert.match(model.trace.map(e => e.text).join('\n'), /crashed in the critical section|token is lost/);
+});
+
+test('TokenRing script-mode events cover normal and invalid paths', () => {
+  const demo = {
+    type: 'MutexDemo',
+    algorithm: 'TokenRing',
+    processes: ['P1', 'P2'],
+    events: [
+      {},
+      { t: 1, op: 'holdToken', on: 'P2' },
+      { t: 2, op: 'passToken', to: 'P1' },
+      { t: 3, op: 'requestCS', on: 'P1' },
+      { t: 4, op: 'releaseCS', on: 'P1' },
+      { t: 5, op: 'releaseCS', on: 'P2' },
+      { t: 6, op: 'dropToken' },
+      { t: 7, op: 'regenerateToken', on: 'P2' },
+      { t: 8, op: 'crash', on: 'P2' },
+      { t: 9, op: 'recover', on: 'P2' },
+      { t: 10, op: 'unknownOp' }
+    ]
+  };
+
+  const model = core.loadFromJsonObject(demo);
+  assert.equal(model.mode, 'script');
+
+  stepN(core, model, demo.events.length + 2);
+  const trace = model.trace.map(e => e.text).join('\n');
+  assert.match(trace, /Loaded scripted scenario/);
+  assert.match(trace, /Script finished/);
+});

tests/00_misc.test.mjs

@@ -0,0 +1,28 @@
+import assert from 'node:assert/strict';
+
+export function stepN(core, model, n) {
+  for (let i = 0; i < n; i += 1) {
+    core.stepOnce(model);
+  }
+}
+
+export function stepUntil(core, model, predicate, maxSteps = 2000, label = 'condition') {
+  for (let i = 0; i < maxSteps; i += 1) {
+    const result = core.stepOnce(model);
+    if (predicate(result)) return { steps: i + 1, result };
+  }
+  throw new Error(`Timeout waiting for ${label} after ${maxSteps} steps`);
+}
+
+export function lastTrace(model) {
+  if (!Array.isArray(model.trace) || model.trace.length === 0) return '';
+  return model.trace[model.trace.length - 1].text;
+}
+
+export function assertSafety(core, model, msg = 'safety should be OK') {
+  assert.equal(core.checkSafety(model).ok, true, msg);
+}
+
+export function inCS(core, model, pid) {
+  return !!core.getProc(model, pid)?.inCS;
+}