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:

Clone the single brand-specific repository
Run npm install (which pulls Level 4 and Level 3 as dependencies)
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:

Loads test cases from all paths in TEST_PATHS
Loads schemas from all paths in SCHEMA_PATHS
Calls Level 4 factory functions to create base test definitions
Calls Level 5 mutator functions to modify or delete as needed
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:

Check your code for style violations:
```
npm run lint
```
If issues are found, automatically fix fixable problems:
```
npm run lint:fix
```
If issues remain after auto-fixing, manually fix them by editing the files.
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

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

Testing & Linting Guidelines

On this page