@forgedock/fd-fastest-cli

Command-line orchestrator for the FD-Fastest performance testing toolkit. The CLI wraps Playwright-driven lab runs, configuration discovery, and report generation so you can measure Next.js applications end to end.

Features

• ⚙️ Commander-based CLI with fd-fastest lab and fd-fastest init
• 🌐 Playwright automation with device + network throttling
• 📊 Web Vitals aggregation from @forgedock/fd-fastest-runtime-next
• 📦 JSON report generation using @forgedock/fd-fastest-reporter-json
• 🪵 Git context capture for every run

Usage

pnpm install
pnpm --filter @forgedock/fd-fastest-cli build

# scaffold config
pnpm fd-fastest init

# run lab tests (ensure your app is running locally)
pnpm fd-fastest lab

Use fd-fastest lab --config path/to/config.ts to target a custom configuration file. Reports are written to the directory defined in the config (reports by default) and include a trace archive plus budget validation output.

Simulated Interactions (INP)

Lab runs now perform lightweight, configurable user interactions so Interaction to Next Paint (INP) is populated without manual scripting. Tune the behaviour via the interactions block in your config:

export default {
  // ...
  interactions: {
    enabled: true,
    strategy: 'first-clickable', // 'selector' or 'random'
    // selector: '#primary-cta', // required when strategy === 'selector'
    interactionTypes: ['click', 'keypress'],
    waitAfterHydration: 1000,
    postInteractionDelay: 750,
  },
};

The CLI waits for hydration, executes the requested actions (click, keypress, input), and then allows a short buffer so web-vitals can report INP. Disable the block entirely (enabled: false) if your app has its own scripted interactions.

Turbopack Bundle Analysis

When next.analyzeBundles is enabled, the CLI automatically inspects Turbopack production builds by reading the manifests under .next/turbopack. Disable this behaviour with next.turbopackBundleAnalysis = false if you only want classic webpack manifest parsing.

PageSpeed Insights

Enable PSI collection to fold Google PageSpeed Insights field and lab data into every report:

export default {
  // ...
  psi: {
    enabled: true,
    strategy: 'mobile', // or 'desktop'
    // apiKey: 'your-api-key', // optional when PSI_API_KEY env var is set
  },
};

Supply the API key either in the config or via the PSI_API_KEY environment variable. The CLI requests one PSI run per unique URL using the configured strategy (default mobile) and merges the first successful result into report.json.

Troubleshooting

• Missing API key – the CLI logs an error and skips PSI without failing the run.
• PSI API errors – network or quota issues surface as warnings but do not block report generation.
• Slow responses – PSI requests run sequentially with a short delay to respect rate limits; large URL sets may take longer to complete.