test: complete tutorial coverage with env var overrides

Add env var overrides to 4 tutorials so they can be tested via the
subprocess harness without hardcoded values:
- document-update/delete: DOCUMENT_ID
- name-register: NAME_LABEL
- identity-update-disable-key: DISABLE_KEY_ID (renamed from KEY_ID)

Add 5 new write tests and extract state from existing tests to chain
the full pipeline (28/28 tutorials now covered).

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: thephez

.env.example

@@ -18,6 +18,10 @@ WITHDRAWAL_ADDRESS=''
 # Used for document-update and document-delete tutorials
 DOCUMENT_ID=''
 
+# DISABLE_KEY_ID is the public key ID to permanently disable (from identity key list)
+# ⚠️ Disabling a key is irreversible
+DISABLE_KEY_ID=''
+
 # NAME_LABEL is an optional username label for name registration (without .dash)
 NAME_LABEL=''
 

1-Identities-and-Names/identity-update-disable-key.mjs

@@ -4,14 +4,17 @@ import { setupDashClient } from '../setupDashClient.mjs';
 const { sdk, keyManager } = await setupDashClient();
 const { identity, signer } = await keyManager.getMaster();
 
-const KEY_ID = 99; // Replace with one of the identity's existing public key IDs
+// Replace with one of the identity's existing public key IDs
+const DISABLE_KEY_ID = Number(process.env.DISABLE_KEY_ID ?? 99);
 
-console.log(`Disabling key ${KEY_ID} on identity ${keyManager.identityId}...`);
+console.log(
+  `Disabling key ${DISABLE_KEY_ID} on identity ${keyManager.identityId}...`,
+);
 
 try {
   await sdk.identities.update({
     identity,
-    disablePublicKeys: [KEY_ID], // Disable public key id KEY_ID
+    disablePublicKeys: [DISABLE_KEY_ID],
     signer,
   });
 

1-Identities-and-Names/name-register.mjs

@@ -5,7 +5,7 @@ const { sdk, keyManager } = await setupDashClient();
 const { identity, identityKey, signer } = await keyManager.getAuth();
 
 // ⚠️ Change this to a unique name to register
-const NAME_LABEL = 'alice';
+const NAME_LABEL = process.env.NAME_LABEL ?? 'alice';
 
 try {
   // Register a DPNS name for the identity

2-Contracts-and-Documents/document-delete.mjs

@@ -10,7 +10,7 @@ const DATA_CONTRACT_ID =
   'FW3DHrQiG24VqzPY4ARenMgjEPpBNuEQTZckV8hbVCG4';
 
 // Replace with your existing document ID
-const DOCUMENT_ID = 'YOUR_DOCUMENT_ID';
+const DOCUMENT_ID = process.env.DOCUMENT_ID ?? 'YOUR_DOCUMENT_ID';
 
 try {
   // Delete the document from the platform

2-Contracts-and-Documents/document-update.mjs

@@ -10,7 +10,7 @@ const DATA_CONTRACT_ID =
   'FW3DHrQiG24VqzPY4ARenMgjEPpBNuEQTZckV8hbVCG4';
 
 // Replace with your existing document ID from the Submit Documents tutorial
-const DOCUMENT_ID = 'YOUR_DOCUMENT_ID';
+const DOCUMENT_ID = process.env.DOCUMENT_ID ?? 'YOUR_DOCUMENT_ID';
 
 try {
   // Fetch the existing document to get current revision

test/assertions.mjs

@@ -68,3 +68,11 @@ export function extractId(stdout) {
     extractFromOutput(stdout, /id:\s*'([^']+)'/)
   );
 }
+
+/**
+ * Extract the key ID from `identity-update-add-key` output.
+ * Matches "Adding key {N} to identity ...".
+ */
+export function extractKeyId(stdout) {
+  return extractFromOutput(stdout, /Adding key (\d+)/);
+}

test/read-write.test.mjs

@@ -1,7 +1,11 @@
 import { describe, it } from 'node:test';
 import assert from 'node:assert/strict';
 import { runTutorial } from './run-tutorial.mjs';
-import { assertTutorialSuccess, extractId } from './assertions.mjs';
+import {
+  assertTutorialSuccess,
+  extractId,
+  extractKeyId,
+} from './assertions.mjs';
 
 // Accumulated state passed forward as env vars to dependent tutorials.
 const state = {};
@@ -24,7 +28,7 @@ describe('Write tutorials (sequential)', { concurrency: 1 }, () => {
       /Identity registered!/,
       `Expected identity registration output.\nSTDOUT: ${result.stdout}\nSTDERR: ${result.stderr}`,
     );
-    console.log(result.stdout)
+    console.log(result.stdout);
   });
 
   it('identity-retrieve', { timeout: 120_000 }, async () => {
@@ -85,10 +89,48 @@ describe('Write tutorials (sequential)', { concurrency: 1 }, () => {
       expectedPatterns: ['Identity updated:'],
       errorPatterns: ['Something went wrong'],
     });
+
+    const keyId = extractKeyId(result.stdout);
+    assert.ok(keyId, `Failed to extract key ID from stdout:\n${result.stdout}`);
+    state.addedKeyId = keyId;
+  });
+
+  it('identity-update-disable-key', { timeout: 120_000 }, async (ctx) => {
+    if (!state.addedKeyId) {
+      ctx.skip('No KEY_ID (identity-update-add-key must pass first)');
+      return;
+    }
+    const result = await runTutorial(
+      '1-Identities-and-Names/identity-update-disable-key.mjs',
+      {
+        env: { DISABLE_KEY_ID: state.addedKeyId },
+        timeoutMs: 120_000,
+      },
+    );
+    assertTutorialSuccess(result, {
+      name: 'identity-update-disable-key',
+      expectedPatterns: ['Identity updated:'],
+      errorPatterns: ['Something went wrong'],
+    });
   });
 
-  // Skipped: identity-update-disable-key.mjs — KEY_ID = 99 hardcoded
-  // Skipped: name-register.mjs — NAME_LABEL = 'alice' hardcoded
+  it('name-register', { timeout: 120_000 }, async () => {
+    const label = `test-${Date.now()}-${Math.random()
+      .toString(36)
+      .slice(2, 6)}`;
+    const result = await runTutorial(
+      '1-Identities-and-Names/name-register.mjs',
+      {
+        env: { NAME_LABEL: label },
+        timeoutMs: 120_000,
+      },
+    );
+    assertTutorialSuccess(result, {
+      name: 'name-register',
+      expectedPatterns: ['Name registered:'],
+      errorPatterns: ['Something went wrong', 'already registered'],
+    });
+  });
 
   // -----------------------------------------------------------------------
   // Phase 2: Contracts
@@ -105,7 +147,10 @@ describe('Write tutorials (sequential)', { concurrency: 1 }, () => {
       errorPatterns: ['Something went wrong'],
     });
     const id = extractId(result.stdout);
-    assert.ok(id, `Failed to extract contract ID from stdout:\n${result.stdout}`);
+    assert.ok(
+      id,
+      `Failed to extract contract ID from stdout:\n${result.stdout}`,
+    );
     state.dataContractId = id;
   });
 
@@ -155,6 +200,13 @@ describe('Write tutorials (sequential)', { concurrency: 1 }, () => {
       expectedPatterns: ['Contract registered:'],
       errorPatterns: ['Something went wrong'],
     });
+
+    const id = extractId(result.stdout);
+    assert.ok(
+      id,
+      `Failed to extract history contract ID from stdout:\n${result.stdout}`,
+    );
+    state.historyContractId = id;
   });
 
   it('contract-register-nft', { timeout: 180_000 }, async () => {
@@ -171,7 +223,9 @@ describe('Write tutorials (sequential)', { concurrency: 1 }, () => {
 
   it('contract-update-minimal', { timeout: 120_000 }, async (ctx) => {
     if (!state.dataContractId) {
-      ctx.skip('No DATA_CONTRACT_ID (contract-register-minimal must pass first)');
+      ctx.skip(
+        'No DATA_CONTRACT_ID (contract-register-minimal must pass first)',
+      );
       return;
     }
     const result = await runTutorial(
@@ -188,13 +242,36 @@ describe('Write tutorials (sequential)', { concurrency: 1 }, () => {
     });
   });
 
+  it('contract-update-history', { timeout: 120_000 }, async (ctx) => {
+    if (!state.historyContractId) {
+      ctx.skip(
+        'No DATA_CONTRACT_ID (contract-register-history must pass first)',
+      );
+      return;
+    }
+    const result = await runTutorial(
+      '2-Contracts-and-Documents/contract-update-history.mjs',
+      {
+        env: { DATA_CONTRACT_ID: state.historyContractId },
+        timeoutMs: 120_000,
+      },
+    );
+    assertTutorialSuccess(result, {
+      name: 'contract-update-history',
+      expectedPatterns: ['Contract updated:'],
+      errorPatterns: ['Something went wrong'],
+    });
+  });
+
   // -----------------------------------------------------------------------
   // Phase 3: Documents (depend on contract from Phase 2)
   // -----------------------------------------------------------------------
 
   it('document-submit', { timeout: 120_000 }, async (ctx) => {
     if (!state.dataContractId) {
-      ctx.skip('No DATA_CONTRACT_ID (contract-register-minimal must pass first)');
+      ctx.skip(
+        'No DATA_CONTRACT_ID (contract-register-minimal must pass first)',
+      );
       return;
     }
     const result = await runTutorial(
@@ -211,11 +288,58 @@ describe('Write tutorials (sequential)', { concurrency: 1 }, () => {
     });
 
     const docId = extractId(result.stdout);
-    assert.ok(docId, `Failed to extract document ID from stdout:\n${result.stdout}`);
+    assert.ok(
+      docId,
+      `Failed to extract document ID from stdout:\n${result.stdout}`,
+    );
     state.documentId = docId;
   });
 
-  // TODO: document-update.mjs and document-delete.mjs need a
-  // `process.env.DOCUMENT_ID ??` prefix before they can be tested here.
-  // Once added, use state.documentId (extracted above) via env var.
+  it('document-update', { timeout: 120_000 }, async (ctx) => {
+    if (!state.dataContractId || !state.documentId) {
+      ctx.skip(
+        'No DATA_CONTRACT_ID or DOCUMENT_ID (earlier tests must pass first)',
+      );
+      return;
+    }
+    const result = await runTutorial(
+      '2-Contracts-and-Documents/document-update.mjs',
+      {
+        env: {
+          DATA_CONTRACT_ID: state.dataContractId,
+          DOCUMENT_ID: state.documentId,
+        },
+        timeoutMs: 120_000,
+      },
+    );
+    assertTutorialSuccess(result, {
+      name: 'document-update',
+      expectedPatterns: ['Document updated:'],
+      errorPatterns: ['Something went wrong'],
+    });
+  });
+
+  it('document-delete', { timeout: 120_000 }, async (ctx) => {
+    if (!state.dataContractId || !state.documentId) {
+      ctx.skip(
+        'No DATA_CONTRACT_ID or DOCUMENT_ID (earlier tests must pass first)',
+      );
+      return;
+    }
+    const result = await runTutorial(
+      '2-Contracts-and-Documents/document-delete.mjs',
+      {
+        env: {
+          DATA_CONTRACT_ID: state.dataContractId,
+          DOCUMENT_ID: state.documentId,
+        },
+        timeoutMs: 120_000,
+      },
+    );
+    assertTutorialSuccess(result, {
+      name: 'document-delete',
+      expectedPatterns: ['Document deleted successfully'],
+      errorPatterns: ['Something went wrong'],
+    });
+  });
 });