feat(wdio-reporter): add launcher service for single test run

[therealbrad]

Description

Add a WDIO launcher service (TestPlanItService) that creates a single test run before any workers start and completes it after all workers finish. This ensures all spec files across all worker batches report to one consolidated test run, solving the issue where oneReport only coordinates workers running simultaneously within the same batch.

Also extracts shared state coordination into shared.ts, adds captureScreenshots as a service option, and splits the monolithic webdriverio-reporter.md doc into 6 focused pages.

Type of Change

• New feature (non-breaking change that adds functionality)
• Documentation update
• Refactoring (no functional changes)

How Has This Been Tested?

• Unit tests

91 tests across 3 test files, all passing:

• service.test.ts (31 tests) — constructor validation, onPrepare lifecycle, resolveIds (string/numeric/not-found), tag resolution, onComplete, afterTest screenshot capture
• shared.test.ts (22 tests) — file path generation, read/write/delete, stale detection, worker count inc/dec, lock acquisition/failure/release
• reporter.test.ts (38 tests) — includes 6 new tests for service-managed mode (adopts shared state IDs, skips run creation/completion, still tracks results)

Coverage for new/modified files:

• service.ts: 98.9% statements, 88% branches
• shared.ts: 100% statements, 88% branches

Test Configuration:

• OS: macOS (Darwin 24.6.0)
• Node version: 24

Checklist

• My code follows the project's style guidelines
• I have performed a self-review of my code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes

Additional Notes

Key files

• packages/wdio-testplanit-reporter/src/service.ts — new launcher service with onPrepare, onComplete, and afterTest hooks
• packages/wdio-testplanit-reporter/src/shared.ts — extracted shared state file coordination (lock, read/write, worker counting)
• packages/wdio-testplanit-reporter/src/types.ts — new TestPlanItServiceOptions type, captureScreenshots option
• packages/wdio-testplanit-reporter/src/reporter.ts — refactored to use shared.ts, added managedByService flag support
• docs/docs/sdk/wdio-*.md — 6 new focused doc pages replacing the monolithic webdriverio-reporter.md

Usage

// wdio.conf.js
import { TestPlanItService } from '@testplanit/wdio-reporter';

export const config = {
  services: [
    [TestPlanItService, {
      domain: 'https://testplanit.example.com',
      apiToken: process.env.TESTPLANIT_API_TOKEN,
      projectId: 1,
      runName: 'E2E Tests - {date}',
      captureScreenshots: true,
    }]
  ],
  reporters: [
    ['@testplanit/wdio-reporter', {
      domain: 'https://testplanit.example.com',
      apiToken: process.env.TESTPLANIT_API_TOKEN,
      projectId: 1,
      autoCreateTestCases: true,
    }]
  ],
};

🤖 Generated with Claude Code