@testspectra/cli 1.1.7 → 1.1.8-rc.2

package/templates/react-component/README.md

@@ -0,0 +1,69 @@
+# TestSpectra React Component Testing Template
+
+A high-performance, real-browser React component testing template powered by **TestSpectra**, **WebdriverIO Browser Runner**, and **Testing Library**.
+
+## 🚀 Features
+
+- **Direct Component Mounting**: Mount TSX components directly in real Chromium/Blink engines using `@testing-library/react`.
+- **Zero Mock Browser**: Real layout calculations, CSS rendering, focus states, and browser events without JSDOM/HappyDOM limitations.
+- **Fast Vite HMR Core**: Instant test startup powered by Vite bundler inside the browser runner.
+- **TestSpectra Matchers**: Comprehensive semantic assertions (`.shouldBeVisible()`, `.shouldExist()`, `expect(el).toHaveText()`).
+
+## 📁 Directory Structure
+
+```
+.
+├── spectra.config.ts        # TestSpectra centralized configuration
+├── wdio.conf.ts             # WebdriverIO Browser Runner + Vite config
+├── tsconfig.json            # TypeScript configuration for JSX & runner types
+└── src/
+    ├── components/          # React components and tests
+    │   ├── Button/
+    │   │   ├── Button.tsx
+    │   │   └── Button.test.tsx
+    │   ├── Badge/
+    │   │   ├── Badge.tsx
+    │   │   └── Badge.test.tsx
+    │   └── Input/
+    │       ├── Input.tsx
+    │       └── Input.test.tsx
+    └── test-utils.tsx       # Common testing helpers & providers
+```
+
+## 🛠️ Usage & Commands
+
+```bash
+# Run all component tests
+pnpm test
+
+# Run component tests in headless mode
+pnpm run test:headless
+
+# Run tests in high-concurrency chunked worker mode
+pnpm run test:chunked
+
+# Type check
+pnpm run type-check
+```
+
+## 📝 Writing Component Tests
+
+```tsx
+import React from 'react';
+import { render } from '@testing-library/react';
+import { expect, $ } from '@wdio/globals';
+import { Button } from './Button';
+
+describe('Button Component', () => {
+  it('renders label and handles user clicks', async () => {
+    let clicked = false;
+    render(<Button label="Submit" onClick={() => (clicked = true)} />);
+
+    const button = await $('button=Submit');
+    await expect(button).toBeDisplayed();
+
+    await button.click();
+    expect(clicked).toBe(true);
+  });
+});
+```

package/templates/react-component/fixtures/component-mock.json

@@ -0,0 +1,12 @@
+{
+  "user": {
+    "name": "Alex Mercer",
+    "role": "Developer",
+    "status": "active"
+  },
+  "labels": {
+    "save": "Save Changes",
+    "cancel": "Cancel",
+    "delete": "Delete Item"
+  }
+}

package/templates/react-component/global-hooks/after/web.hook.ts

@@ -0,0 +1,3 @@
+export default async function () {
+  // Global after hook for web component testing suite
+}

package/templates/react-component/global-hooks/before/web.hook.ts

@@ -0,0 +1,3 @@
+export default async function () {
+  // Global before hook for web component testing suite
+}

package/templates/react-component/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@testspectra/template-react-component",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "test": "spectra test",
+    "test:headed": "spectra test --headed",
+    "spectra": "spectra",
+    "doctor": "spectra doctor",
+    "watch": "spectra watch",
+    "type-check": "tsc -b",
+    "sync-types": "spectra sync-types",
+    "postinstall": "spectra sync-types"
+  },
+  "devDependencies": {
+    "@testspectra/cli": "link:../..",
+    "@testspectra/matchers": "link:../../../tools/matchers",
+    "@testspectra/react": "link:../../../tools/react",
+    "@types/node": "^20.14.0",
+    "@types/react": "^18.3.3",
+    "@types/react-dom": "^18.3.0",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "typescript": "^5.4.5"
+  }
+}

package/templates/react-component/page-objects/BadgeComponent/web.ts

@@ -0,0 +1,23 @@
+class BadgeComponent {
+  /** Root badge element */
+  get root() {
+    return Spectra.get("[data-testid='testspectra-badge']");
+  }
+
+  /** Dot indicator element */
+  get dot() {
+    return Spectra.get("[data-testid='badge-dot']");
+  }
+
+  /** Badge label text element */
+  get label() {
+    return Spectra.get("[data-testid='badge-label']");
+  }
+
+  /** Lookup badge by severity attribute */
+  bySeverity(severity: 'info' | 'success' | 'warning' | 'danger') {
+    return Spectra.get(`[data-testid='testspectra-badge'][data-severity='${severity}']`);
+  }
+}
+
+export default new BadgeComponent();

package/templates/react-component/page-objects/ButtonComponent/web.ts

@@ -0,0 +1,23 @@
+class ButtonComponent {
+  /** Root button element */
+  get root() {
+    return Spectra.get("[data-testid='testspectra-button']");
+  }
+
+  /** Label element inside button */
+  get label() {
+    return Spectra.get("[data-testid='button-label']");
+  }
+
+  /** Optional icon element */
+  get icon() {
+    return Spectra.get("[data-testid='button-icon']");
+  }
+
+  /** Lookup button element by visible text */
+  byText(text: string) {
+    return Spectra.get(`button*=${text}`);
+  }
+}
+
+export default new ButtonComponent();

package/templates/react-component/page-objects/InputComponent/web.ts

@@ -0,0 +1,13 @@
+class InputComponent {
+  /** Root input element */
+  get root() {
+    return Spectra.get("[data-testid='testspectra-input']");
+  }
+
+  /** Lookup input element by placeholder substring */
+  byPlaceholder(placeholder: string) {
+    return Spectra.get(`input[placeholder*='${placeholder}']`);
+  }
+}
+
+export default new InputComponent();

package/templates/react-component/specs/BadgeComponent/TC-0002-badge-severities-and-dot/spec.md

@@ -0,0 +1,18 @@
+---
+id: TC-0002
+title: Verify default badge with info severity
+priority: Critical
+caseType: Positive
+status: automated
+coverage:
+  web: automated
+---
+
+# TC-0002: Badge Default Rendering
+
+Verify that `<Badge />` renders with the default `info` severity when no `severity` prop is provided.
+
+## Test Steps
+
+1. Mount `<Badge label="System Active" />`.
+2. Verify the badge is visible, shows the correct label text, and has `data-severity="info"`.

package/templates/react-component/specs/BadgeComponent/TC-0002-badge-severities-and-dot/web.test.tsx

@@ -0,0 +1,11 @@
+import { Badge } from '../../../src/components/Badge/Badge.js';
+import { withProviders } from '../../../src/test-utils.js';
+
+it('Verify default badge with info severity', async () => {
+  await Spectra.mount(withProviders(<Badge label="System Active" />));
+
+  // Assert via BadgeComponent component object
+  await BadgeComponent.root.shouldBeVisible();
+  await BadgeComponent.label.shouldHaveText('System Active');
+  await BadgeComponent.root.shouldHaveAttribute('data-severity', 'info');
+});

package/templates/react-component/specs/BadgeComponent/TC-0006-badge-success-with-dot/spec.md

@@ -0,0 +1,18 @@
+---
+id: TC-0006
+title: Verify badge with success severity and dot indicator
+priority: High
+caseType: Positive
+status: automated
+coverage:
+  web: automated
+---
+
+# TC-0006: Badge Success Severity with Dot Indicator
+
+Verify that `<Badge />` renders the `success` severity styling and shows a dot indicator when the `dot` prop is set.
+
+## Test Steps
+
+1. Mount `<Badge label="Completed" severity="success" dot />`.
+2. Verify the badge is visible with `data-severity="success"` and the dot indicator is visible.

package/templates/react-component/specs/BadgeComponent/TC-0006-badge-success-with-dot/web.test.tsx

@@ -0,0 +1,10 @@
+import { Badge } from '../../../src/components/Badge/Badge.js';
+import { withProviders } from '../../../src/test-utils.js';
+
+it('Verify badge with success severity and dot indicator', async () => {
+  await Spectra.mount(withProviders(<Badge label="Completed" severity="success" dot />));
+
+  await BadgeComponent.root.shouldBeVisible();
+  await BadgeComponent.root.shouldHaveAttribute('data-severity', 'success');
+  await BadgeComponent.dot.shouldBeVisible();
+});

package/templates/react-component/specs/BadgeComponent/TC-0007-badge-by-severity-lookup/spec.md

@@ -0,0 +1,18 @@
+---
+id: TC-0007
+title: Verify dynamic lookup using bySeverity helper
+priority: Medium
+caseType: Positive
+status: automated
+coverage:
+  web: automated
+---
+
+# TC-0007: Badge Lookup by Severity Helper
+
+Verify that multiple `<Badge />` instances rendered together can be located individually via `BadgeComponent.bySeverity(...)`.
+
+## Test Steps
+
+1. Mount two badges: `<Badge label="Warning Alert" severity="warning" />` and `<Badge label="Critical Error" severity="danger" />`.
+2. Verify each badge can be located and is visible via `BadgeComponent.bySeverity('warning')` and `BadgeComponent.bySeverity('danger')`.

package/templates/react-component/specs/BadgeComponent/TC-0007-badge-by-severity-lookup/web.test.tsx

@@ -0,0 +1,16 @@
+import { Badge } from '../../../src/components/Badge/Badge.js';
+import { withProviders } from '../../../src/test-utils.js';
+
+it('Verify dynamic lookup using bySeverity helper', async () => {
+  await Spectra.mount(
+    withProviders(
+      <div>
+        <Badge label="Warning Alert" severity="warning" />
+        <Badge label="Critical Error" severity="danger" />
+      </div>,
+    ),
+  );
+
+  await BadgeComponent.bySeverity('warning').shouldBeVisible();
+  await BadgeComponent.bySeverity('danger').shouldBeVisible();
+});

package/templates/react-component/specs/BadgeComponent/suite.md

@@ -0,0 +1,12 @@
+---
+id: badge-component-suite
+name: Badge Component Suite
+executionOrder: 2
+tags:
+  - component
+  - badge
+  - status
+---
+
+# Badge Component Testing Suite
+Verification of badge labels, severity color variants, and dot indicators.

package/templates/react-component/specs/ButtonComponent/TC-0001-button-rendering-and-click/spec.md

@@ -0,0 +1,19 @@
+---
+id: TC-0001
+title: Verify button render, text, and click with Spectra DSL
+priority: Critical
+caseType: Positive
+status: automated
+coverage:
+  web: automated
+---
+
+# TC-0001: Button Rendering and Click Interaction
+
+Verify that the `<Button />` component renders with the requested label and variant, and fires its `onClick` callback when clicked.
+
+## Test Steps
+
+1. Mount `<Button label="Save Changes" variant="primary" />`.
+2. Verify the button is visible with the correct label and `data-variant` attribute.
+3. Click the button and verify the `onClick` callback fires.

package/templates/react-component/specs/ButtonComponent/TC-0001-button-rendering-and-click/web.test.tsx

@@ -0,0 +1,28 @@
+import { Button } from '../../../src/components/Button/Button.js';
+import { withProviders } from '../../../src/test-utils.js';
+
+it('Verify button render, text, and click with Spectra DSL', async () => {
+  let isClicked = false;
+
+  // Spectra.mount() renders into the shared root — no explicit cleanup between mounts needed.
+  await Spectra.mount(
+    withProviders(
+      <Button
+        label="Save Changes"
+        variant="primary"
+        onClick={() => {
+          isClicked = true;
+        }}
+      />,
+    ),
+  );
+
+  // TestSpectra Ambient Component Object (ButtonComponent)
+  await ButtonComponent.root.shouldBeVisible();
+  await ButtonComponent.root.shouldHaveText('Save Changes');
+  await ButtonComponent.root.shouldHaveAttribute('data-variant', 'primary');
+  await ButtonComponent.root.click();
+
+  // Verify callback state
+  expect(isClicked).toBe(true);
+});

package/templates/react-component/specs/ButtonComponent/TC-0004-disabled-button-not-clickable/spec.md

@@ -0,0 +1,19 @@
+---
+id: TC-0004
+title: Verify disabled button cannot be clicked
+priority: High
+caseType: Negative
+status: automated
+coverage:
+  web: automated
+---
+
+# TC-0004: Disabled Button Interaction
+
+Verify that a disabled `<Button />` renders in a disabled state and its `onClick` callback does not fire when clicked.
+
+## Test Steps
+
+1. Mount `<Button label="Disabled Action" disabled />`.
+2. Verify the button is visible and disabled.
+3. Attempt to click the button and verify the `onClick` callback does not fire.

package/templates/react-component/specs/ButtonComponent/TC-0004-disabled-button-not-clickable/web.test.tsx

@@ -0,0 +1,22 @@
+import { Button } from '../../../src/components/Button/Button.js';
+
+it('Verify disabled button cannot be clicked', async () => {
+  let isClicked = false;
+
+  await Spectra.mount(
+    <Button
+      label="Disabled Action"
+      disabled
+      onClick={() => {
+        isClicked = true;
+      }}
+    />,
+  );
+
+  await ButtonComponent.root.shouldBeVisible();
+  await ButtonComponent.root.shouldBeDisabled();
+
+  // Attempt click - should not fire callback
+  await ButtonComponent.root.click().catch(() => {});
+  expect(isClicked).toBe(false);
+});

package/templates/react-component/specs/ButtonComponent/TC-0005-button-renders-icon/spec.md

@@ -0,0 +1,18 @@
+---
+id: TC-0005
+title: Verify button renders optional icon
+priority: Medium
+caseType: Positive
+status: automated
+coverage:
+  web: automated
+---
+
+# TC-0005: Button Optional Icon Rendering
+
+Verify that `<Button />` renders an optional leading icon when the `icon` prop is provided.
+
+## Test Steps
+
+1. Mount `<Button label="Download Report" icon={...} />` with an icon element.
+2. Verify the icon is visible and renders the expected content.

package/templates/react-component/specs/ButtonComponent/TC-0005-button-renders-icon/web.test.tsx

@@ -0,0 +1,8 @@
+import { Button } from '../../../src/components/Button/Button.js';
+
+it('Verify button renders optional icon', async () => {
+  await Spectra.mount(<Button label="Download Report" icon={<span data-testid="button-icon">📥</span>} />);
+
+  await ButtonComponent.icon.shouldBeVisible();
+  await ButtonComponent.icon.shouldHaveText('📥');
+});

package/templates/react-component/specs/ButtonComponent/suite.md

@@ -0,0 +1,12 @@
+---
+id: button-component-suite
+name: Button Component Suite
+executionOrder: 1
+tags:
+  - component
+  - button
+  - atoms
+---
+
+# Button Component Testing Suite
+Verification of isolated button props, event listeners, accessibility, and visual variants.

package/templates/react-component/specs/InputComponent/TC-0003-input-typing-and-clear/spec.md

@@ -0,0 +1,20 @@
+---
+id: TC-0003
+title: Verify input placeholder and typing interaction
+priority: Critical
+caseType: Positive
+status: automated
+coverage:
+  web: automated
+---
+
+# TC-0003: Input Typing and Placeholder
+
+Verify that `<Input />` renders its placeholder, accepts typed text, and fires `onChange` with the typed value.
+
+## Test Steps
+
+1. Mount `<Input placeholder="Enter email address" />` with an `onChange` handler.
+2. Verify the input is visible and the placeholder is discoverable.
+3. Type `test@example.com` into the input and verify the value updates.
+4. Verify the `onChange` handler received the typed value.

package/templates/react-component/specs/InputComponent/TC-0003-input-typing-and-clear/web.test.tsx

@@ -0,0 +1,28 @@
+import { Input } from '../../../src/components/Input/Input.js';
+import { withProviders } from '../../../src/test-utils.js';
+
+it('Verify input placeholder and typing interaction', async () => {
+  let currentVal = '';
+
+  await Spectra.mount(
+    withProviders(
+      <Input
+        placeholder="Enter email address"
+        onChange={(e) => {
+          currentVal = e.target.value;
+        }}
+      />,
+    ),
+  );
+
+  // 1. Assert element is visible via InputComponent
+  await InputComponent.root.shouldBeVisible();
+  await InputComponent.byPlaceholder('email address').shouldBeVisible();
+
+  // 2. Type text using Spectra DSL
+  await InputComponent.root.type('test@example.com');
+  await InputComponent.root.shouldHaveValue('test@example.com');
+
+  // 3. Verify onChange state
+  expect(currentVal).toBe('test@example.com');
+});

package/templates/react-component/specs/InputComponent/TC-0008-disabled-input-not-editable/spec.md

@@ -0,0 +1,18 @@
+---
+id: TC-0008
+title: Verify disabled input cannot be typed into
+priority: High
+caseType: Negative
+status: automated
+coverage:
+  web: automated
+---
+
+# TC-0008: Disabled Input State
+
+Verify that a disabled `<Input />` renders in a disabled state.
+
+## Test Steps
+
+1. Mount `<Input disabled placeholder="Disabled field" />`.
+2. Verify the input is visible and disabled.

package/templates/react-component/specs/InputComponent/TC-0008-disabled-input-not-editable/web.test.tsx

@@ -0,0 +1,9 @@
+import { Input } from '../../../src/components/Input/Input.js';
+import { withProviders } from '../../../src/test-utils.js';
+
+it('Verify disabled input cannot be typed into', async () => {
+  await Spectra.mount(withProviders(<Input disabled placeholder="Disabled field" />));
+
+  await InputComponent.root.shouldBeVisible();
+  await InputComponent.root.shouldBeDisabled();
+});

package/templates/react-component/specs/InputComponent/suite.md

@@ -0,0 +1,12 @@
+---
+id: input-component-suite
+name: Input Component Suite
+executionOrder: 3
+tags:
+  - component
+  - input
+  - forms
+---
+
+# Input Component Testing Suite
+Verification of text inputs, placeholder labels, keyboard typing, and onChange events.

package/templates/react-component/spectra.config.ts

@@ -0,0 +1,27 @@
+import { defineConfig } from "@testspectra/cli";
+
+export default defineConfig({
+  webConfig: {
+    baseUrl: "http://localhost:5173",
+    maxConcurrentSessions: "4",
+    headless: true,
+    implicitWait: "5000",
+    pageLoadTimeout: "30000",
+    scriptTimeout: "30000",
+    parallelizationMode: "testcase",
+  },
+  browsers: [
+    {
+      id: "chrome-desktop",
+      type: "chrome",
+      mobileEmulation: false,
+    },
+  ],
+  executionConfig: {
+    networkMonitoringEnabled: true,
+    fastResponseTime: "200",
+    normalResponseTime: "1000",
+    monitoredDomains: [],
+    environmentVariables: [],
+  },
+});

package/templates/react-component/src/components/Badge/Badge.tsx

@@ -0,0 +1,60 @@
+import React from 'react';
+
+export interface BadgeProps {
+  label: string;
+  severity?: 'info' | 'success' | 'warning' | 'danger';
+  dot?: boolean;
+}
+
+export const Badge: React.FC<BadgeProps> = ({
+  label,
+  severity = 'info',
+  dot = false,
+}) => {
+  const getColors = () => {
+    switch (severity) {
+      case 'success':
+        return { bg: '#dcfce7', text: '#15803d' };
+      case 'warning':
+        return { bg: '#fef9c3', text: '#a16207' };
+      case 'danger':
+        return { bg: '#fee2e2', text: '#b91c1c' };
+      case 'info':
+      default:
+        return { bg: '#e0f2fe', text: '#0369a1' };
+    }
+  };
+
+  const { bg, text } = getColors();
+
+  return (
+    <span
+      data-testid="testspectra-badge"
+      data-severity={severity}
+      style={{
+        display: 'inline-flex',
+        alignItems: 'center',
+        gap: '6px',
+        padding: '2px 8px',
+        borderRadius: '9999px',
+        backgroundColor: bg,
+        color: text,
+        fontSize: '12px',
+        fontWeight: 600,
+      }}
+    >
+      {dot && (
+        <span
+          data-testid="badge-dot"
+          style={{
+            width: '6px',
+            height: '6px',
+            borderRadius: '50%',
+            backgroundColor: text,
+          }}
+        />
+      )}
+      <span data-testid="badge-label">{label}</span>
+    </span>
+  );
+};