@eggjs/bin

@eggjs/bin

egg developer tool, base on oclif.

Install

npm i @eggjs/bin --save-dev

Usage

Add egg-bin to package.json scripts:

{
  "scripts": {
    "dev": "egg-bin dev",
    "test-local": "egg-bin test",
    "test": "npm run lint -- --fix && npm run test-local",
    "cov": "egg-bin cov",
    "lint": "eslint .",
    "ci": "npm run lint && npm run cov"
  }
}

Command

All the commands support these specific options:

• --inspect
• --inspect-brk
• --typescript / --ts enable typescript support. Auto detect from package.json's pkg.egg.typescript, or pkg.dependencies.typescript/pkg.devDependencies.typescript.
• --base / --baseDir application's root path, default to process.cwd().
• --require will add to execArgv, support multiple. Also support read from package.json's pkg.egg.require
• --dry-run / -d whether dry-run the test command, just show the command

egg-bin [command] --inspect
egg-bin [command] --inspect-brk
egg-bin [command] --typescript
egg-bin [command] --base /foo/bar

dev

Start dev cluster on local env, it will start a master, an agent and a worker.

egg-bin dev

dev options

• --framework egg web framework root path.
• --port server port. If not specified, the port is obtained in the following order: egg.js configuration config/config.*.js > process.env.EGG_BIN_DEFAULT_PORT > 7001 > other available ports.
• --workers worker process number, default to 1 worker at local mode.
• --sticky start a sticky cluster server, default to false.

debug/inspect on VSCode

Create .vscode/launch.json file:

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "Egg Debug",
      "runtimeExecutable": "npm",
      "runtimeArgs": ["run", "dev", "--", "--inspect-brk"],
      "console": "integratedTerminal",
      "restart": true,
      "autoAttachChildProcesses": true
    },
    {
      "type": "node",
      "request": "launch",
      "name": "Egg Test",
      "runtimeExecutable": "npm",
      "runtimeArgs": ["run", "test-local", "--", "--inspect-brk"],
      "autoAttachChildProcesses": true
    }
  ]
}

test

Using vitest to run test.

egg-bin test [...files] [options]

• files is optional, default to test/**/*.test.ts
• test/fixtures, test/node_modules is always excluded.

auto load test/.setup.ts

If test/.setup.ts (or .setup.js) exists, it will be auto-added as the first vitest setupFile.

test
  ├── .setup.ts
  └── foo.test.ts

auto-inject @eggjs/mock/setup_vitest

For egg applications, @eggjs/mock/setup_vitest is automatically registered as a vitest setup file when @eggjs/mock is installed, handling app lifecycle (beforeAll / afterEach / afterAll).

auto use @eggjs/tegg-vitest/runner

If @eggjs/tegg-vitest is installed in the project, its runner is automatically detected and injected into the vitest config.

test options

• --timeout / -t milliseconds, default to 60000
• --no-timeout disable timeout
• --grep / -g only run tests matching pattern
• --bail / -b stop after first test failure
• --changed / -c only run tests for changed files (matches test/**/*.test.(js|ts))
• --watch / -w run in watch mode

test environment

You can set TESTS env to specify test files, supports comma-separated glob patterns.

TESTS=test/a.test.ts egg-bin test

The reporter can be set with TEST_REPORTER env (any vitest reporter), default is default.

TEST_REPORTER=verbose egg-bin test

The test timeout can be set with TEST_TIMEOUT env, default is 60000 ms.

TEST_TIMEOUT=2000 egg-bin test

cov

Using vitest with v8 coverage to run code coverage. Supports all test options above.

Coverage reports are written to coverage/ and include: text-summary, json-summary, json, lcov, cobertura.

cov options

• -x add a glob pattern to exclude from coverage, supports multiple
• also supports all test options above.

cov environment

You can set COV_EXCLUDES env to add glob patterns to exclude from coverage (comma-separated).

COV_EXCLUDES="app/plugins/c*,app/autocreate/**" egg-bin cov

Breaking Changes (v8)

Migrated from Mocha to Vitest

The test and cov commands now use vitest instead of Mocha. This brings native TypeScript support, faster execution, and built-in watch mode, but removes some Mocha-specific options:

Removed flags:

Old flag	Reason
--parallel / -p	Vitest handles parallelism natively via worker pools
--jobs / -j	Replaced by vitest's built-in pool configuration
--auto-agent	Mocha-specific, no equivalent needed in vitest
--prerequire	Use test/.setup.ts setupFile instead
--c8	Coverage is now configured inside vitest, use -x for excludes

Removed environment variables:

Old env var	Reason
MOCHA_FILE	Mocha-specific, vitest runner is auto-detected

Changed output format:

Test output now follows vitest's format. Assertions in test scripts that match mocha output (e.g. "N passing") should be updated to vitest output (e.g. "N passed").

Migration guide:

• Replace before() / after() hooks with beforeAll() / afterAll() (vitest naming)
• Import vitest globals explicitly in .ts setup files: import { beforeAll, afterEach } from 'vitest'
• Plain .js test files can use globals directly (vitest globals: true is enabled by default)
• Remove --parallel / --jobs flags from your npm scripts

Custom egg-bin for your team

See https://oclif.io/docs/configuring_your_cli/

License

MIT

Contributors

Made with contributors-img.