Testing & Linting Guidelines

This document covers the testing framework, linting standards, and quality assurance practices used across the MiningOS ecosystem.

For repository structure including the tests/ directory layout, see Repository Structure.

---

Overview

MiningOS follows consistent testing and linting patterns to ensure code quality, reliability, and maintainability. The test architecture is designed around a key principle: developers working on brand-specific workers should only need to clone a single repository and run npm test to execute the full test suite of the inheritance chain.

Tools

Tool	Purpose	Version
Brittle	Test framework	3.7.0+
Standard.js	JavaScript linting	17.1.0+

Inheritance Model

Tests are defined at template levels (Level 3 and 4) and automatically inherited by brand-specific workers (Level 5). This means:

• Level 3 (miningos-tpl-wrk-thing) — Common tests for all devices (getSnap, getStats, getConfig)

• Level 4 (miningos-tpl-wrk-miner, -container, etc.) — Category-specific tests (powerMode, led, reboot)

• Level 5 (miningos-wrk-miner-antminer, -avalon, -whatsminer, etc.) — Only modifications for hardware differences

For the complete inheritance hierarchy, see Repository Structure — Repository Hierarchy and Architecture — Class Hierarchy.

---

Script Reference

Script	Command	Description
npm test	brittle tests/*.js	Run all test files
npm run lint	standard	Check code style
npm run lint:fix	standard --fix	Auto-fix linting issues

---

Test Directory Structure

Worker repositories follow a consistent test structure (see Repository Structure — Standard Directory Structure):

tests/
├── cases/                    # Test case definitions
│   ├── stats.js              # Statistics tests
│   ├── powerMode.js          # Power mode tests (miner)
│   ├── led.js                # LED control tests (miner)
│   └── reboot.js             # Reboot tests (miner)
├── schema/                   # Validation schemas
│   ├── base.js               # Base success schemas
│   ├── stats.js              # Statistics schemas
│   └── [feature].js          # Feature-specific schemas
├── executors.js              # Test execution functions (Level 4 only)
├── utils.js                  # Test utilities
└── [worker].test.js          # Main test entry point

---

Test Inheritance Architecture

Design Rationale

MiningOS is designed to be user-friendly and architecturally simple. A developer working on a brand-specific worker (Level 5) should only need to:

1. Clone the single brand-specific repository

2. Run npm install (which pulls Level 4 and Level 3 as dependencies)

3. Run npm test

This single command automatically executes the full inherited test suite — common device tests from Level 3, category-specific tests from Level 4, with any brand-specific modifications from Level 5 applied.

Key benefits:

• Minimal setup — No need to clone multiple repositories

• Automatic inheritance — Tests defined at parent levels run automatically

• Write less code — Level 5 only defines what differs from the parent

• Consistent coverage — All miners (or any device type) share common test baselines

For creating new workers with proper test inheritance, see Adding New Worker — Testing Infrastructure.

Inheritance Chain

Level 3: miningos-tpl-wrk-thing
    └── tests/device.test.js      (base test framework)
    └── tests/utils.js            (base utilities, initializes SCHEMA_PATHS/TEST_PATHS)
    └── tests/cases/*.js          (common device tests: getSnap, getStats, getConfig)
    └── tests/schema/*.js         (base validation schemas)

Level 4: miningos-tpl-wrk-miner (and other device templates)
    └── tests/miner.test.js       (re-exports Level 3, adds executors)
    └── tests/utils.js            (extends Level 3 utils, adds Level 4 paths)
    └── tests/cases/*.js          (category tests: powerMode, led, reboot)
    └── tests/schema/*.js         (category schemas: miner stats, config)

Level 5: miningos-wrk-miner-antminer (and other brand workers)
    └── tests/miner.test.js       (imports functions, implements execution)
    └── tests/utils.js            (extends Level 4 utils, adds Level 5 paths)
    └── tests/cases/*.js          (mutators: modify/delete inherited tests)
    └── tests/schema/*.js         (mutators: mark optional fields, override structures)

How Test Accumulation Works

When a Level 5 worker runs tests, the path arrays accumulate through the inheritance chain:

After Level 3 loads:
  TEST_PATHS   = [thing/tests/cases]
  SCHEMA_PATHS = [thing/tests/schema]

After Level 4 loads:
  TEST_PATHS   = [thing/tests/cases, miner/tests/cases]
  SCHEMA_PATHS = [thing/tests/schema, miner/tests/schema]

After Level 5 loads:
  TEST_PATHS   = [thing/tests/cases, miner/tests/cases, antminer/tests/cases]
  SCHEMA_PATHS = [thing/tests/schema, miner/tests/schema, antminer/tests/schema]

The test executor then:

1. Loads test cases from all paths in TEST_PATHS

2. Loads schemas from all paths in SCHEMA_PATHS

3. Calls Level 4 factory functions to create base test definitions

4. Calls Level 5 mutator functions to modify or delete as needed

5. Executes the merged, modified test suite

Linting With Standard.js

Code Style Rules

MiningOS follows Standard.js style guide:

• 2 spaces for indentation

• Single quotes for strings

• No semicolons (ASI-safe style)

• No unused variables

• Space after keywords (if (condition), not if(condition))

• === instead of == (except for null checks)

For naming conventions, see Contribution Workflow — Naming Conventions.

Running Linter

Follow these steps to check and fix code style:

1. Check your code for style violations:

   npm run lint

2. If issues are found, automatically fix fixable problems:

   npm run lint:fix

3. If issues remain after auto-fixing, manually fix them by editing the files.

4. Run the linter again to verify all issues are resolved:

   npm run lint

File Header Pattern

All JavaScript files must start with 'use strict' (see Code Documentation Standards — File Headers):

'use strict'

const SomeModule = require('some-module')

// ... rest of code

---

Related Documentation

Contributor Guide

• Repository Structure — Directory layout and test file locations

• Contribution Workflow — Development setup and code standards

• Branching & PR Conventions — PR checklist including test requirements

• Code Documentation Standards — JSDoc and file header requirements

• Adding New Worker — Test infrastructure for new workers

Architecture & Reference

• Architecture Guide — System design and inheritance hierarchy

• Supported Devices — Hardware requiring test coverage

External Resources

• Brittle — Test framework documentation

• Standard.js — JavaScript style guide and linter

• Holepunch Documentation — Hyperswarm and Hyperbee testing