skills/plugins/suaveplan-testing-workflow/skills/testing-workflow/SKILL.md

name, description

name	description
testing-workflow	Testing commands, CI/CD integration, advanced turborepo filtering, E2E/Storybook testing, development workflow, and troubleshooting for the Suaveplan monorepo

Testing Workflow & CI/CD

Use this skill when running tests, setting up CI/CD, troubleshooting build issues, or following the development workflow in the Suaveplan monorepo.

Package Testing

# Lint a package
bun run lint --filter=@suaveplan/<package-name>

# Type check a package
bun run typecheck --filter=@suaveplan/<package-name>

# Run unit/integration tests
bun run test --filter=@suaveplan/<package-name>

# Run tests with coverage
bun run test:coverage --filter=@suaveplan/<package-name>

# Run E2E tests (Playwright)
bun run e2e --filter=@suaveplan/<package-name>

Workspace-Wide Testing

bunx turbo lint              # Lint all packages
bunx turbo typecheck         # Type check all packages
bunx turbo test              # Run all tests
bunx turbo test:coverage     # All tests with coverage
bunx turbo e2e               # All E2E tests

Advanced Turborepo Filtering

# Package and its dependencies
bunx turbo build --filter=@suaveplan/web...

# Package and its dependents
bunx turbo build --filter=...@suaveplan/core

# Affected since main branch
bunx turbo build --filter=...[main]

# Affected since specific commit
bunx turbo build --filter=...[HEAD^1]

# Combine filters (AND)
bunx turbo test --filter=@suaveplan/ui --filter=...@suaveplan/design-system

# Multiple packages (OR)
bunx turbo test --filter=@suaveplan/{ui,forms,auth-ui}

# Exclude packages
bunx turbo test --filter=!@suaveplan/storybook

E2E Testing

9 packages have Playwright E2E tests:

@suaveplan/web, @suaveplan/admin, @suaveplan/auth-ui, @suaveplan/dashboard, @suaveplan/onboarding, @suaveplan/billing, @suaveplan/forms, @suaveplan/ui, @suaveplan/storybook

# Single package E2E
bun run e2e --filter=@suaveplan/web

# Multiple packages E2E
bunx turbo e2e --filter=@suaveplan/{web,admin,auth-ui}

# All E2E tests
bunx turbo e2e

Storybook Testing

# Start Storybook dev server
bun run storybook --filter=@suaveplan/ui

# Run visual tests against Storybook
bun run test:storybook --filter=@suaveplan/ui

Testing Best Practices

• Write clear, focused test descriptions
• Use arrange-act-assert pattern
• Test edge cases and error conditions
• Keep tests fast and deterministic
• Always add { timeout: 5000 } to it()/test() calls (30000 for integration/async)
• Use provider: 'istanbul' for vitest coverage (not v8)
• Install @vitest/coverage-istanbul (from catalog:testing)

Timeout Syntax

// Unit test
it('description', { timeout: 5000 }, () => {
  // test body
});

// Async test
it('async description', { timeout: 10000 }, async () => {
  // async test body
});

Tree-Shaking Verification

Before publishing any package:

1. Verify sideEffects declaration in package.json
2. Test bundle sizes: bunx vite-bundle-visualizer
3. Confirm no side effects in entry points:
   • Review src/index.ts for immediate execution
   • Check for global mutations or polyfills
   • Ensure only export statements exist

Development Workflow

Starting Development

bun install          # Install dependencies
bunx turbo build     # Build all packages
bunx turbo dev       # Start development servers

Making Changes

git checkout -b feature/my-feature        # 1. Create feature branch
# 2. Make changes to packages
bunx turbo test --filter=...[HEAD^1]      # 3. Run affected tests
bunx turbo test:coverage --filter=...[HEAD^1]  # 4. Check coverage
bunx turbo lint typecheck --filter=...[HEAD^1] # 5. Lint and type check
git add . && git commit -m "feat: msg"    # 6. Commit changes

Phase Completion Requirements

Before marking a phase as complete, verify:

1. All tests passing: bunx turbo test
2. 95%+ test coverage: bunx turbo test:coverage
3. 90%+ documentation coverage: bun run docs:check
4. No lint errors: bunx turbo lint
5. No type errors: bunx turbo typecheck
6. E2E tests passing: bunx turbo e2e (for applicable packages)
7. Tree-shaking configured: All packages have sideEffects declaration

CI/CD Integration

GitHub Actions Example

name: CI

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: oven-sh/setup-bun@v1
        with:
          bun-version: latest

      - name: Install dependencies
        run: bun install

      - name: Build
        run: bunx turbo build

      - name: Lint
        run: bunx turbo lint

      - name: Type check
        run: bunx turbo typecheck

      - name: Test
        run: bunx turbo test:coverage

      - name: E2E tests
        run: bunx turbo e2e

      - name: Upload coverage
        uses: codecov/codecov-action@v3

Remote Caching (Optional)

bunx turbo login          # Login to Vercel
bunx turbo link           # Link your repository
bunx turbo build --remote-cache  # Run with remote cache

Troubleshooting

React Version Conflicts

Symptoms: Error: Minified React error #31, TypeError: Cannot read properties of null (reading 'useContext'), build fails during static page generation.

Root Cause: Multiple React versions in monorepo.

Solution: Use Bun overrides with exact versions and nuclear clean install. See suaveplan-dependency-management skill for full steps.

Clear Cache

bunx turbo clean                    # Clear Turborepo cache
rm -rf node_modules && rm bun.lockb && bun install  # Clear Bun cache

Debug Mode

bunx turbo test --filter=@suaveplan/core --verbosity=3  # Verbose logging
bunx turbo test --summarize                              # Task execution summary

Type Errors

bunx turbo build --filter=...@suaveplan/types  # Build types for all packages
bun tsc --noEmit --pretty                       # Type check with verbose output

Tool Selection

• MCP servers > Native tools > Basic alternatives
• Use specialized tools for their designed purpose
• Prefer powerful search tools (Grep, Glob) over bash