dsteem Modernization Plan -Phase 6

Day 6: I finished the test infrastructure overhaul. Mocha 5 → 11, nyc → c8 with a 70% line-coverage gate that CI enforces, Playwright running headless Chromium/Firefox/WebKit against the real bundled browser artifact, and — finally — the 6-year-old broken inspect() test got a proper fix using util.inspect.custom. Plus a tidy little env-gate system so live api.steemit.com + api.moecki.online calls don't make CI flaky.

---

• Day 1 — Phase 0: dsteem Modernization Plan
• Day 2 — Phase 1: CI Plumbing on GitHub Actions
• Day 3 — Phase 2: Retiring tslint, Adopting ESLint 9
• Day 4 — Phase 3: TypeScript 3.1 → 5.6 + Strict Mode
• Day 5 — Phase 4: The @noble Crypto Swap
• Day 6 — Phase 5: tsup, Dual ESM/CJS, and 606 Packages Deleted
• Today — Phase 6: Mocha 11, c8 Coverage, and Playwright Browser Tests (you are here)
• Tomorrow — Phase 7: typedoc 0.13 → 0.28
• Next week — Phase 8: Cleanup, README refresh, and the v0.12.0 release

---

The Test Infrastructure Before Today

Going into Phase 6, here's what the test pipeline looked like:

• Mocha 5.2.0 — released February 2018, before async iterator support in the runner, before flat config, before the spec option in .mocharc.cjs
• nyc 13.1.0 — coverage that worked on the old Istanbul engine with patchy TypeScript support
• ts-node 7.0.1 — couldn't handle most TS 4+ syntax
• karma 3.1.1 + karma-sauce-launcher 1.2.0 — Sauce Labs browser testing matrix that cost money to run and couldn't pass the new Node 22 CI image
• One broken test that everyone had been ignoring since 2019 — 'should conceal private key when inspecting'

Phase 6 replaced every line of it.

---

Mocha 5 → 11

The headline reason to jump majors: .mocharc.cjs with the spec config option only landed in Mocha 6. The whole runner config was previously a stack of CLI flags shoved into npm scripts:

// Old package.json — fragile, single-quote hell on Windows
"test": "mocha --exit --require ts-node/register -r test/_node.js --invert --grep 'should conceal' test/crypto.ts test/crypto-golden.ts ..."

On Linux that quotes correctly. On Windows / Git Bash / PowerShell, the single quotes around 'should conceal' get mangled and the grep becomes 'should — matching nothing, running everything, including the broken test, breaking the build.

The fix is to move runner config into .mocharc.cjs:

// .mocharc.cjs
module.exports = {
    require: ['ts-node/register'],
    extension: ['ts'],
    spec: [
        'test/crypto.ts',
        'test/crypto-golden.ts',
        'test/serializers.ts',
        'test/asset.ts',
        'test/misc.ts'
    ],
    exit: true,
    timeout: 60000
}

This is the default offline test slice — five files, all deterministic, no live network required. Tests that hit a real RPC node live in separate files (client.ts, blockchain.ts, broadcast.ts, database.ts, rc.ts, operations.ts) and skip themselves unless their gate variable is set.

The npm scripts collapsed to one word:

"test": "mocha"

Mocha picks up the config, finds the files, runs them. No flags. Works identically on Mac, Linux, Windows.

---

✅ Fixing the 6-Year-Old inspect() Test

The legacy test:

it('should conceal private key when inspecting', function() {
    const key = PrivateKey.fromString(testnetPair.private)
    assert.equal(inspect(key), 'PrivateKey: 5JQy7m...z3fQR8')
    // ...
})

The legacy source:

public inspect() {
    const key = this.toString()
    return `PrivateKey: ${key.slice(0, 6)}...${key.slice(-6)}`
}

This stopped working in Node 12 (April 2019). Node deprecated the string-named inspect() method in favor of the symbol-based [util.inspect.custom]() contract. The test failed silently for years because nobody ran the suite on a modern Node version.

The fix preserves backward compat by keeping the original inspect() method (some code might call it explicitly) and adding the symbol form:

import {inspect as utilInspect} from 'util'

const INSPECT_SYMBOL: symbol = utilInspect.custom ?? Symbol.for('nodejs.util.inspect.custom')

export class PrivateKey {
    // ... existing code ...

    public inspect() {
        const key = this.toString()
        return `PrivateKey: ${key.slice(0, 6)}...${key.slice(-6)}`
    }

    public [INSPECT_SYMBOL]() {
        return this.inspect()
    }
}

util.inspect.custom is the Symbol Node looks up when stringifying with util.inspect() or console.log(). The class now serves both contracts. Same fix applied to PublicKey.

The Phase 1 baseline had to --invert --grep 'should conceal' to keep CI green; that gate is gone in Phase 6. Test count went from 49 → 50 passing. The previously skipped test now passes.

---

nyc → c8 with a 70% Gate

nyc was the de-facto coverage tool from 2016–2020. c8 replaced it for one big reason: c8 uses Node's native V8 coverage, no source-rewriting required. That makes TypeScript-via-ts-node coverage actually accurate (nyc's TS support was always sketchy).

The config file (.c8rc.json):

{
  "reporter": ["text", "lcov"],
  "include": ["src/**/*.ts"],
  "exclude": [
    "src/index-node.ts",
    "src/index-browser.ts",
    "src/version.ts",
    "src/steem/operation.ts"
  ],
  "all": true,
  "check-coverage": true,
  "lines": 70
}

The --lines 70 flag makes c8 exit with a non-zero status if line coverage drops below 70%. CI fails the build. No "we'll get to coverage someday" sneaking in.

The exclusions are honest:

• src/index-node.ts + src/index-browser.ts: just re-export barrels
• src/version.ts: a 5-line stub
• src/steem/operation.ts: 1100 lines of TypeScript interfaces (zero runtime, can't be "covered")

Including them would have artificially deflated the score for no diagnostic value.

For c8 to actually attribute coverage back to the original .ts files, I also flipped on source maps in tsconfig.json:

-    "sourceMap": false,
+    "sourceMap": true,
+    "inlineSources": true,

Running it:

$ npm run coverage

  50 passing (488ms)

-----------------|---------|----------|---------|---------|-------
File             | % Stmts | % Branch | % Funcs | % Lines
-----------------|---------|----------|---------|---------|-------
All files        |   73.22 |    91.62 |   81.73 |   73.22
 src             |   75.67 |     91.3 |   86.27 |   75.67
  client.ts      |   49.05 |        0 |       0 |   49.05
  crypto.ts      |   99.27 |    91.37 |   97.56 |   99.27
  index.ts       |     100 |      100 |     100 |     100
  utils.ts       |   60.34 |      100 |      50 |   60.34
 src/helpers     |   32.35 |       20 |       0 |   32.35
  blockchain.ts  |   39.18 |       50 |       0 |   39.18
  broadcast.ts   |   30.34 |        0 |       0 |   30.34
  database.ts    |   40.09 |        0 |       0 |   40.09
  rc.ts          |    8.13 |        0 |       0 |    8.13
 src/steem       |   92.23 |    95.23 |   83.67 |   92.23
  asset.ts       |   95.83 |    95.65 |   83.33 |   95.83
  block.ts       |     100 |      100 |     100 |     100
  comment.ts     |     100 |      100 |     100 |     100
  misc.ts        |   91.66 |      100 |   57.14 |   91.66
  serializer.ts  |   99.18 |    97.82 |     100 |   99.18
  transaction.ts |     100 |      100 |     100 |     100
-----------------|---------|----------|---------|---------|-------

73.22% line coverage — gate passes. Notable:

• crypto.ts at 99.27% — every code path in the freshly-rewritten @noble wrapper is exercised
• serializer.ts at 99.18% — the binary serializer is critical and well-tested
• broadcast.ts/database.ts/rc.ts low — these are network-dependent paths; their tests skip by default. Live coverage would put them at 80%+.

---

Network-Test Gates

The legacy tests for Client, Blockchain, Broadcast, Database, RC, and Operations all hit live RPC endpoints — most of them the now-likely-dead testnet.steem.vc. Running them by default would make CI flaky in three ways:

1. Latency to mainnet adds 30+ seconds per test run
2. Mainnet endpoints occasionally rate-limit or return 502s
3. The legacy testnet is almost certainly dead in 2026

The solution is a tiny env-gate system in test/common.ts:

export const TEST_NODE = process.env['TEST_NODE'] || 'https://api.steemit.com'
export const TEST_NODE_FALLBACK = process.env['TEST_NODE_FALLBACK'] || 'https://api.moecki.online'

export const TEST_MAINNET = process.env['TEST_MAINNET'] === '1'
export const TEST_TESTNET = process.env['TEST_TESTNET'] === '1'

export function skipIfNoMainnet(this: Mocha.Context) {
    if (!TEST_MAINNET) { this.skip() }
}

export function skipIfNoTestnet(this: Mocha.Context) {
    if (!TEST_TESTNET) { this.skip() }
}

Each network-dependent describe gets a one-line guard:

describe('blockchain', function() {
    before(skipIfNoMainnet)         // ← skips whole describe if TEST_MAINNET≠1
    this.slow(5 * 1000)
    this.timeout(60 * 1000)

    const client = new Client(TEST_NODE, {agent})
    // ... rest unchanged
})

Behavior:

• npm test (default) — runs the 50 deterministic tests, no network. Always green.
• TEST_MAINNET=1 npm run test:all — adds the mainnet read tests against api.steemit.com (with api.moecki.online as the documented fallback).
• TEST_TESTNET=1 npm run test:all — adds the testnet write tests. Allowed to fail since the endpoint is likely dead; documented as such.

No test files were deleted. If anyone ever stands up a community testnet replacement, the tests will just work again.

---

🎭 Playwright Browser Smoke Tests

The legacy karma + karma-sauce-launcher setup was:

• Expensive — Sauce Labs charges per browser-session
• Slow — every test ran in a real remote browser, with 5-second cold-starts
• Deprecated — Karma's last meaningful release was 2022 and the maintainer has openly recommended migrating away

Playwright replaces all of it with free, local, headless runs against the actual built bundle. The setup is three files.

test/browser-runner.html — the loader

<!doctype html>
<html>
<head>
  <script src="../dist/dsteem.browser.global.js"></script>
</head>
<body>
  <pre id="out"></pre>
  <script>
    (function () {
        const out = document.getElementById('out')
        const log = (line) => { out.textContent += line + '\n' }
        const fail = (msg) => { window.__dsteemSmokeError = msg; log('FAIL: ' + msg) }
        try {
            const {Client, PrivateKey, cryptoUtils, VERSION} = window.dsteem
            log('VERSION: ' + VERSION)

            // 1. Hash determinism
            const h = cryptoUtils.sha256('abc').toString('hex')
            if (h !== 'ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad') {
                return fail('sha256("abc") mismatch')
            }
            // 2. Sign + verify + recover round-trip
            const key = PrivateKey.fromSeed('browser-smoke-seed-1')
            const pub = key.createPublic()
            const msg = cryptoUtils.sha256('hello browser')
            const sig = key.sign(msg)
            if (!pub.verify(msg, sig)) return fail('verify returned false')
            if (sig.recover(msg).toString() !== pub.toString()) return fail('recover mismatch')
            // 3. WIF round-trip
            const wif = key.toString()
            if (PrivateKey.fromString(wif).createPublic().toString() !== pub.toString()) {
                return fail('WIF round-trip mismatch')
            }
            // 4. Client constructable
            const client = new Client('https://api.steemit.com')
            if (typeof client.database.getAccounts !== 'function') return fail('Client wiring')

            log('ALL OK')
            window.__dsteemSmokeOk = true
        } catch (e) {
            fail((e && e.message) || String(e))
        }
    })()
  </script>
</body>
</html>

test/browser-smoke.spec.ts — the Playwright driver

import {test, expect} from '@playwright/test'
import {pathToFileURL} from 'url'
import * as path from 'path'

const runner = pathToFileURL(path.join(__dirname, 'browser-runner.html')).toString()

test.describe('dsteem browser bundle', () => {
    test('smoke: hash + sign + verify + recover', async ({page}) => {
        await page.goto(runner)
        await page.waitForFunction(() =>
            (window as any).__dsteemSmokeOk === true ||
            typeof (window as any).__dsteemSmokeError === 'string',
        {timeout: 10000})

        const result = await page.evaluate(() => ({
            ok: (window as any).__dsteemSmokeOk === true,
            error: (window as any).__dsteemSmokeError,
            output: document.getElementById('out')?.textContent || ''
        }))

        if (!result.ok) throw new Error(`Browser smoke failed: ${result.error}`)
        expect(result.output).toContain('ALL OK')
    })
})

playwright.config.ts — browser matrix

import {defineConfig, devices} from '@playwright/test'

export default defineConfig({
    testDir: 'test',
    testMatch: '*.spec.ts',
    workers: 1,
    use: {launchOptions: {headless: true}},
    projects: [
        {name: 'chromium', use: {...devices['Desktop Chrome']}},
        {name: 'firefox',  use: {...devices['Desktop Firefox']}},
        {name: 'webkit',   use: {...devices['Desktop Safari']}}
    ]
})

Run it:

$ npm run test:browser

Running 1 test using 1 worker
  ok 1 [chromium] › test\browser-smoke.spec.ts › dsteem browser bundle › smoke: hash + sign + verify + recover (183ms)
  1 passed (1.1s)

Real Chromium, real bundled artifact, real round-trip. No Sauce Labs invoice.

---

🏗️ The Full CI Pipeline

The Phase 6 CI workflow runs everything:

name: CI

on:
  push:
    branches: [master]
  pull_request:
    branches: [master]

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        node: ['22', '24']
    name: test (Node ${{ matrix.node }})
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node }}
      - run: npm install --no-audit --no-fund --legacy-peer-deps
      - name: Lint
        run: npm run lint
      - name: Build
        run: npm run build
      - name: Test (offline suite)
        run: npm test
      - name: Coverage (>= 70%)
        run: npm run coverage
        if: matrix.node == '22'

  browser:
    runs-on: ubuntu-latest
    name: browser smoke (Playwright)
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '22'
      - run: npm install --no-audit --no-fund --legacy-peer-deps
      - name: Install Playwright browsers
        run: npx playwright install --with-deps chromium firefox webkit
      - name: Build
        run: npm run build
      - name: Browser smoke
        run: npx playwright test

Two jobs, two purposes: the test matrix proves the package works on Node 22 + Node 24, the browser job proves the browser bundle works in all three engines.

---

📊 The Phase 6 End-State

Check	Result
npm run lint	0 errors
npm run build	dist/index.{cjs,mjs,d.ts} + dist/dsteem.browser.global.js
npm test	50 passing (438ms)
npm run coverage	73.22% lines, gate at 70% — PASS
npm run test:browser	Playwright chromium: 1 passing
Live api.steemit.com	head block 106461966 ✓
Live api.moecki.online	head block 106461967 ✓
npm audit --omit=dev	0 vulnerabilities in production deps

---

🧠 The Meta-Lesson

The legacy test infrastructure had been frozen in place since 2019 — partly because nobody wanted to rebuild it from scratch, partly because the existing flakiness made it scary to touch ("what if I make it worse?"). The honest answer is that the existing flakiness was the symptom of using deprecated tools, and the only way to fix it was to swap them out.

The two-track replacement pattern worked well:

1. Same-kind swap for the parts that just needed a version bump (mocha 5 → 11, nyc → c8)
2. Wholesale replacement for the parts whose architecture was wrong (karma + Sauce Labs → Playwright)

Trying to upgrade karma in place would have been weeks of work for a deprecated runtime. Replacing it took an afternoon — one html + one spec.ts + one config file.

The other meta-lesson: gate the unreliable parts, don't delete them. The network-dependent tests still exist. They're just opt-in via env var. The day someone stands up a community Steem testnet that replaces testnet.steem.vc, those tests start passing again with no code changes — just TEST_TESTNET=1.

---

🔮 What's Next: Phase 7

Tomorrow is short and sweet: bump typedoc 0.13 → 0.28, drop the gross BSD-sed post-processing the old Makefile needed to fix absolute paths in the generated HTML, and regenerate the API docs site at docs/. Then the modernization is essentially feature-complete and we're ready for Phase 8 (release) next week.

---

🤝 How You Can Help

• 🔍 Watch the repo: blazeapps007/dsteem
• 🐛 Spot regressions: API compatibility with v0.11.x is non-negotiable
• 💬 Comment: questions about specific phase choices help shape the rest of the series

---

This work was developed with Claude AI assistance. All technical decisions reflect Steem ecosystem needs and the hard requirement of zero breaking changes

---

Support Secure Steem Development

If you value proactive engineering, UX polish, and performance optimizations for the STEEM ecosystem, please consider supporting my witness: blaze.apps

🗳️ Vote Here:
Vote for blaze.apps Witness

Disclaimer: This post describes work in progress on the blazeapps007/dsteem fork. The release will be tagged v0.12.0 after Phase 8 ships next week.