docmirror/dev-sidecar · error

FreeEye runtime config is required.

Error message

FreeEye runtime config is required.

What it means

`runTests` destructures `config` from its options and requires it to be a non-null object; otherwise it throws `FreeEye runtime config is required.` The free-eye test runner needs runtime settings (applied to every loaded test) and will not guess defaults. This is a fail-fast validation at the public entry point.

Source

Thrown at packages/core/src/modules/plugin/free-eye/client.js:96

    for (const testTag of testCls.getPrereqs()) {
      if (!doneTests.includes(testTag)) {
        allPrereqsDone = false
        break
      }
    }
    if (allPrereqsDone) {
      return testCls
    }
  }
  return null
}

async function runTests (options = {}) {
  const { testsDir, config } = options

  const globalConfig = (config && typeof config === 'object') ? config : null
  if (!globalConfig) {
    throw new Error('FreeEye runtime config is required.')
  }

  const globalResults = {}
  const summaries = []
  const todoTests = await loadAllTests(testsDir, globalConfig)
  console.log(
    `Loaded ${todoTests.length} tests: ${
      todoTests.map(t => t.getTestTag()).join(' ')}`,
  )

  const doneTests = []
  while (todoTests.length > 0) {
    const TestCls = getNextTest(todoTests, doneTests)
    if (!TestCls) {
      break
    }

    const testGroup = new TestCls(globalConfig, globalResults)

View on GitHub (pinned to 7710cd56cc)

Solutions

1. Always pass `config` as a plain object: `runTests({ testsDir, config: freeEyeConfig })`.
2. Load the plugin's config from `DevSidecar.config.get().plugin['free-eye']` and pass that object.
3. Fix the option key name if you passed the config under a different property.
4. Await any async config loader before invoking runTests so you do not pass undefined.

Example fix

// before
await runTests({ testsDir })
// after
const config = DevSidecar.config.get().plugin['free-eye']
await runTests({ testsDir, config })

const config = DevSidecar.config.get()?.plugin?.['free-eye']
if (!config || typeof config !== 'object') {
  throw new Error('free-eye config missing; cannot run tests')
}
await runTests({ testsDir, config })

function isFreeEyeConfig (v) {
  return v !== null && typeof v === 'object' && !Array.isArray(v)
}

try {
  await runTests({ testsDir, config })
} catch (err) {
  if (err.message === 'FreeEye runtime config is required.') {
    console.error('Pass { config } object from plugin settings')
  } else { throw err }
}

When it happens

Trigger: Calling `runTests()` with no arguments, with `{ testsDir }` only, or with `config: null/undefined` (or a non-object such as a string), from packages/core/src/modules/plugin/free-eye/client.js:96.

Common situations: Migrating code that previously called an older zero-config test runner; a caller that loads config asynchronously and passes it before it resolves (undefined); spreading an options object where the config key was misspelled (`cfg` vs `config`).

Understand the failure class

Background: "Must pass :limit option" / "Missing required option" — required option errors explained — this error's family across 41 libraries.

Related errors

• Tests directory not found: ${resolvedDir}
• 无效的代理 IP 地址: ${ip}
• 无效的代理端口号: ${port}
• 证书路径为空，无法安装根证书。请确认证书文件已生成。
• 未指定日志类型，无法配置并获取日志对象！！！

AI-assisted analysis of docmirror/dev-sidecar@7710cd56cc (2026-08-31). Data as JSON: /api/errors/41e4d220b04667c3. Report an issue: GitHub.