VoiceAssist Development Workflow Guide

Version: 1.0.0 Date: 2025-11-21 Status: Production Ready Project: VoiceAssist Enterprise Medical AI Assistant

Table of Contents

1. Git Workflow & Branching Strategy
2. Code Review Process
3. Testing Requirements
4. CI/CD Pipelines
5. Deployment Procedures
6. Documentation Standards
7. Code Style Guide
8. Performance Guidelines
9. Security Guidelines
10. Troubleshooting

1. Git Workflow & Branching Strategy

1.1 Branch Naming Conventions

All branches must follow a strict naming convention to ensure clarity and automated tooling compatibility.

Format

<type>/<ticket-id>-<short-description>

Branch Types

Examples

# Good
feature/VA-123-add-dark-mode-toggle
bugfix/VA-456-fix-websocket-reconnection
hotfix/VA-789-patch-xss-vulnerability
refactor/VA-234-extract-chat-hooks

# Bad (avoid)
john-new-feature
fix-bug
update
feature-123

Protected Branches

1.2 Commit Message Format

We follow Conventional Commits specification for automated changelog generation and semantic versioning.

Format

<type>(<scope>): <subject>

[optional body]

[optional footer(s)]

Types

Scope Examples

Web App:

• auth - Authentication/authorization
• chat - Chat interface
• voice - Voice mode
• ui - UI components
• api - API integration
• state - State management

Admin Panel:

• dashboard - Dashboard features
• kb - Knowledge base management
• users - User management
• analytics - Analytics features

Shared:

• deps - Dependencies
• config - Configuration
• types - TypeScript types

Commit Message Examples

# Feature addition (MINOR version bump)
feat(chat): add message reaction functionality

Implement emoji reactions to chat messages with real-time
updates via WebSocket. Users can add multiple reactions per
message.

Closes VA-123

# Bug fix (PATCH version bump)
fix(auth): resolve token refresh race condition

Fixed issue where multiple simultaneous requests could trigger
concurrent token refresh attempts, causing authentication errors.

Added mutex lock to ensure single refresh process.

Fixes VA-456

# Breaking change (MAJOR version bump)
feat(api)!: migrate to v2 authentication endpoints

BREAKING CHANGE: Auth endpoints moved from /auth/* to /api/v2/auth/*
Clients must update API base URLs.

Migration guide: docs/MIGRATION_V2.md

Refs VA-789

# Performance improvement (PATCH version bump)
perf(voice): optimize audio buffer processing

Reduced audio processing latency by 40% through worker thread
implementation and buffer pooling.

Closes VA-234

# Documentation update (no version bump)
docs(readme): update installation instructions

Added troubleshooting section for common npm/pnpm issues.

# Revert commit
revert: feat(chat): add message reaction functionality

This reverts commit abc123def456.

Reason: Performance regression in real-time updates.

Commit Message Rules

1. Subject line:

   • Use imperative mood ("add" not "added" or "adds")
   • No period at the end
   • Maximum 72 characters
   • Lowercase after type

2. Body:

   • Wrap at 72 characters
   • Explain what and why, not how
   • Separate from subject with blank line

3. Footer:

   • Reference issues: Closes VA-123, Fixes VA-456, Refs VA-789
   • Breaking changes: Start with BREAKING CHANGE:
   • Co-authors: Co-authored-by: Name <email@example.com>

Commit Message Template

Create .gitmessage in repository root:

# <type>(<scope>): <subject>
# |<----  Using a Maximum Of 72 Characters  ---->|

# [optional body]
# |<----   Try To Limit Each Line to a Maximum Of 72 Characters   ---->|

# [optional footer(s)]
# --- COMMIT END ---
# Type can be:
#   feat     (new feature)
#   fix      (bug fix)
#   docs     (documentation)
#   style    (formatting)
#   refactor (refactoring)
#   perf     (performance)
#   test     (testing)
#   build    (build system)
#   ci       (CI config)
#   chore    (other)
#   revert   (revert commit)
# --------------------
# Remember:
#   • Use imperative mood ("add" not "added")
#   • No period at end of subject
#   • Reference issues (Closes VA-123)
#   • Breaking changes: BREAKING CHANGE: description
# --------------------

Configure git to use template:

git config commit.template .gitmessage

1.3 Pull Request (PR) Template

GitHub PR Template

Create .github/PULL_REQUEST_TEMPLATE.md:

## Description

<!-- Provide a brief description of the changes -->

## Type of Change

<!-- Mark relevant items with [x] -->

- [ ] 🚀 Feature (new functionality)
- [ ] 🐛 Bug fix (fixes an issue)
- [ ] 🔒 Security fix
- [ ] ⚡ Performance improvement
- [ ] ♻️ Refactor (no functional changes)
- [ ] 📝 Documentation update
- [ ] 🧪 Test addition/update
- [ ] 🔧 Configuration/infrastructure change
- [ ] 💥 Breaking change

## Related Issues

<!-- Link related issues -->

Closes #
Fixes #
Refs #

## Changes Made

<!-- List key changes -->

-
-
-

## Screenshots/Videos

<!-- If applicable, add screenshots or videos -->

## Testing

<!-- Describe testing performed -->

### Manual Testing

- [ ] Tested in local development environment
- [ ] Tested in staging environment
- [ ] Tested on Chrome
- [ ] Tested on Firefox
- [ ] Tested on Safari
- [ ] Tested on mobile devices
- [ ] Tested with screen reader (accessibility)

### Automated Testing

- [ ] Unit tests added/updated
- [ ] Integration tests added/updated
- [ ] E2E tests added/updated
- [ ] All tests passing locally
- [ ] Test coverage maintained/improved

## Performance Impact

<!-- Check all that apply -->

- [ ] No performance impact
- [ ] Performance improved (describe below)
- [ ] Performance degraded (describe below and justify)

<!-- If performance changed, provide metrics -->

## Security Considerations

<!-- Check all that apply -->

- [ ] No security impact
- [ ] Reviewed for XSS vulnerabilities
- [ ] Reviewed for CSRF vulnerabilities
- [ ] Reviewed for SQL injection
- [ ] Input validation added/reviewed
- [ ] Authentication/authorization checked
- [ ] Sensitive data handling reviewed
- [ ] HIPAA compliance maintained

## Breaking Changes

<!-- If breaking change, describe migration path -->

## Deployment Notes

<!-- Special deployment instructions, if any -->

## Checklist

- [ ] Code follows project style guidelines
- [ ] Self-review completed
- [ ] Comments added for complex logic
- [ ] Documentation updated
- [ ] No new warnings generated
- [ ] Tests added and passing
- [ ] Dependent changes merged
- [ ] Accessibility tested
- [ ] i18n keys added if needed

## Reviewer Notes

<!-- Anything specific for reviewers to focus on -->

## Post-Merge Actions

<!-- Actions required after merge -->

- [ ] Update related documentation
- [ ] Notify stakeholders
- [ ] Monitor error rates
- [ ] Update changelog

1.4 Merge Strategies

Squash Merge (Recommended for most PRs)

Use for feature branches to keep main branch history clean.

# Via GitHub UI
# Select "Squash and merge"

# Or via command line
git checkout main
git merge --squash feature/VA-123-new-feature
git commit -m "feat(feature): add new feature (#123)"

When to use:

• Feature branches with many commits
• Bug fix branches
• Work-in-progress branches with messy history

Benefits:

• Clean, linear history on main
• Easy to revert entire features
• Better changelog generation

Merge Commit

Use for release branches or important milestone merges.

git checkout main
git merge --no-ff release/v1.2.0

When to use:

• Release branches
• Hotfix branches (to preserve urgency context)
• Large feature integrations from develop

Rebase and Merge

Use rarely, only for very clean, well-structured commits.

git checkout feature/VA-123-new-feature
git rebase main
git checkout main
git merge --ff-only feature/VA-123-new-feature

When to use:

• Small, atomic changes
• Commits already well-structured
• Documentation updates

1.5 Git Hooks

We use Husky for git hooks to enforce quality standards.

Installation

# Install Husky
pnpm add -D husky

# Initialize Husky
pnpm exec husky install

# Add to package.json
{
  "scripts": {
    "prepare": "husky install"
  }
}

Pre-commit Hook

.husky/pre-commit:

#!/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.sh"

# Run lint-staged for changed files only
pnpm exec lint-staged

# Run type checking
pnpm run type-check

# Check for console.log statements (warn only)
if git diff --cached --name-only --diff-filter=ACM | grep -E '\.(ts|tsx|js|jsx)$' | xargs grep -n "console\.log" 2>/dev/null; then
  echo "⚠️  Warning: Found console.log statements. Please remove before committing to main."
fi

# Check for debugger statements (error)
if git diff --cached --name-only --diff-filter=ACM | grep -E '\.(ts|tsx|js|jsx)$' | xargs grep -n "debugger" 2>/dev/null; then
  echo "❌ Error: Found debugger statements. Please remove."
  exit 1
fi

# Check for .only in tests (error)
if git diff --cached --name-only --diff-filter=ACM | grep -E '\.test\.(ts|tsx|js|jsx)$' | xargs grep -n "\.only" 2>/dev/null; then
  echo "❌ Error: Found .only in tests. Remove before committing."
  exit 1
fi

Commit-msg Hook

.husky/commit-msg:

#!/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.sh"

# Validate commit message format
pnpm exec commitlint --edit "$1"

Pre-push Hook

.husky/pre-push:

#!/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.sh"

# Run all tests before push
echo "🧪 Running tests before push..."
pnpm run test

# Check if pushing to protected branches
current_branch=$(git symbolic-ref HEAD | sed -e 's,.*/\(.*\),\1,')
protected_branches=("main" "develop" "staging")

for branch in "${protected_branches[@]}"; do
  if [ "$current_branch" = "$branch" ]; then
    echo "❌ Error: Direct push to $branch is not allowed."
    echo "Please create a pull request instead."
    exit 1
  fi
done

Lint-staged Configuration

package.json:

{
  "lint-staged": {
    "*.{ts,tsx}": ["eslint --fix", "prettier --write"],
    "*.{js,jsx}": ["eslint --fix", "prettier --write"],
    "*.{json,md,yml,yaml}": ["prettier --write"],
    "*.{css,scss}": ["prettier --write"]
  }
}

Commitlint Configuration

commitlint.config.js:

module.exports = {
  extends: ["@commitlint/config-conventional"],
  rules: {
    "type-enum": [
      2,
      "always",
      ["feat", "fix", "docs", "style", "refactor", "perf", "test", "build", "ci", "chore", "revert"],
    ],
    "type-case": [2, "always", "lower-case"],
    "type-empty": [2, "never"],
    "scope-case": [2, "always", "lower-case"],
    "subject-empty": [2, "never"],
    "subject-full-stop": [2, "never", "."],
    "subject-case": [2, "always", "lower-case"],
    "header-max-length": [2, "always", 72],
    "body-leading-blank": [2, "always"],
    "body-max-line-length": [2, "always", 100],
    "footer-leading-blank": [2, "always"],
    "footer-max-line-length": [2, "always", 100],
  },
};

1.6 Git Workflow Example

Complete Feature Development Workflow

# 1. Ensure main branch is up to date
git checkout main
git pull origin main

# 2. Create feature branch
git checkout -b feature/VA-123-add-voice-controls

# 3. Make changes and commit regularly
git add src/components/VoiceControls.tsx
git commit -m "feat(voice): add voice control component"

git add src/components/VoiceControls.test.tsx
git commit -m "test(voice): add tests for voice controls"

# 4. Keep branch updated with main
git fetch origin
git rebase origin/main

# 5. Push to remote
git push origin feature/VA-123-add-voice-controls

# 6. Create Pull Request via GitHub UI

# 7. Address review feedback
git add src/components/VoiceControls.tsx
git commit -m "refactor(voice): address PR feedback"
git push origin feature/VA-123-add-voice-controls

# 8. After approval, squash and merge via GitHub UI

# 9. Clean up local branches
git checkout main
git pull origin main
git branch -d feature/VA-123-add-voice-controls

Hotfix Workflow

# 1. Create hotfix branch from main
git checkout main
git pull origin main
git checkout -b hotfix/VA-789-security-patch

# 2. Make urgent fix
git add src/utils/sanitize.ts
git commit -m "fix(security): patch XSS vulnerability"

# 3. Push and create PR
git push origin hotfix/VA-789-security-patch

# 4. After approval, merge without squashing (preserve context)
# Use merge commit via GitHub UI

# 5. Tag the release
git checkout main
git pull origin main
git tag -a v1.2.1 -m "Security patch release"
git push origin v1.2.1

2. Code Review Process

2.1 Review Checklist

Reviewer Checklist Template

Use this checklist for every code review:

## Code Review Checklist

### Functionality

- [ ] Code does what the PR description says
- [ ] Edge cases handled appropriately
- [ ] Error handling is comprehensive
- [ ] User experience is intuitive
- [ ] Accessibility requirements met (WCAG 2.1 AA)

### Code Quality

- [ ] Code is readable and maintainable
- [ ] No unnecessary complexity
- [ ] Functions are small and focused (< 50 lines)
- [ ] No code duplication (DRY principle)
- [ ] Naming is clear and consistent
- [ ] Comments explain "why", not "what"
- [ ] No commented-out code

### TypeScript/JavaScript

- [ ] Proper TypeScript types (no `any`)
- [ ] Type safety maintained
- [ ] Async/await used correctly
- [ ] Promise errors handled
- [ ] No memory leaks (event listeners cleaned up)
- [ ] No console.log or debugger statements

### React Best Practices

- [ ] Components are properly modularized
- [ ] Hooks used correctly (dependencies array)
- [ ] No unnecessary re-renders
- [ ] Props are properly typed
- [ ] State management is appropriate
- [ ] Side effects properly handled (useEffect)
- [ ] Keys used correctly in lists

### Performance

- [ ] No performance regressions
- [ ] Expensive operations memoized
- [ ] Images optimized
- [ ] Lazy loading implemented where appropriate
- [ ] Bundle size impact acceptable

### Testing

- [ ] Unit tests added for new functions
- [ ] Integration tests added for new features
- [ ] Edge cases tested
- [ ] Error scenarios tested
- [ ] Test coverage maintained (80%+)
- [ ] Tests are deterministic (no flaky tests)

### Security

- [ ] Input validation implemented
- [ ] XSS vulnerabilities addressed
- [ ] CSRF protection in place
- [ ] Authentication/authorization correct
- [ ] No sensitive data in logs
- [ ] Dependencies have no known vulnerabilities
- [ ] HIPAA compliance maintained

### API Integration

- [ ] API calls properly typed
- [ ] Loading states handled
- [ ] Error states handled
- [ ] Retry logic implemented
- [ ] Rate limiting respected
- [ ] Timeouts configured

### UI/UX

- [ ] Responsive design works on all breakpoints
- [ ] Loading indicators shown
- [ ] Error messages are user-friendly
- [ ] Forms have proper validation
- [ ] Keyboard navigation works
- [ ] Focus management correct
- [ ] Color contrast meets WCAG standards

### Documentation

- [ ] README updated if needed
- [ ] API documentation updated
- [ ] Comments added for complex logic
- [ ] Migration guide provided (if breaking change)
- [ ] Changelog updated

### Git/Process

- [ ] Branch name follows conventions
- [ ] Commit messages follow conventions
- [ ] PR description is clear
- [ ] All CI checks pass
- [ ] No merge conflicts
- [ ] Changes are atomic (focused on one thing)

2.2 Review Process

Step-by-Step Review Process

For Reviewers:

1. Initial Assessment (5 minutes)

   # Check out the PR branch
   gh pr checkout 123
   
   # Review the PR description and changes
   # Verify CI checks are passing

2. Code Review (30-60 minutes)

   • Read through all changes systematically
   • Use the review checklist above
   • Test locally if needed
   • Add inline comments for specific issues
   • Suggest improvements with code examples

3. Testing (15-30 minutes)

   # Install dependencies
   pnpm install
   
   # Run tests
   pnpm test
   
   # Start dev server and test manually
   pnpm dev
   
   # Check for console errors or warnings

4. Submit Review

   • Approve: All checks pass, no issues found
   • Request Changes: Issues that must be fixed
   • Comment: Suggestions or questions, no blocking issues

For PR Authors:

1. Before Requesting Review

   # Self-review your changes
   git diff origin/main...HEAD
   
   # Run all checks locally
   pnpm run lint
   pnpm run type-check
   pnpm test
   
   # Ensure PR description is complete

2. Respond to Feedback

   • Address all comments (even if you disagree)
   • Ask for clarification if needed
   • Mark conversations as resolved after fixing
   • Thank reviewers for their time

3. After Approval

   • Squash and merge
   • Delete the branch
   • Close related issues

2.3 Approval Requirements

Required Approvals by Branch

Exception Process

For urgent hotfixes:

1. Create hotfix PR
2. Tag with urgent label
3. Request expedited review in Slack
4. Single approval from tech lead sufficient
5. Must include post-deployment verification plan

2.4 Common Feedback Patterns

Code Smells to Watch For

1. Large Components

// ❌ Bad: Component too large (200+ lines)
function UserDashboard() {
  // 200+ lines of logic and JSX
}

// ✅ Good: Split into smaller components
function UserDashboard() {
  return (
    <div>
      <UserHeader />
      <UserStats />
      <UserActivity />
      <UserSettings />
    </div>
  );
}

2. Missing Error Handling

// ❌ Bad: Unhandled promise rejection
async function fetchUserData(userId: string) {
  const response = await fetch(`/api/users/${userId}`);
  return response.json();
}

// ✅ Good: Proper error handling
async function fetchUserData(userId: string): Promise<User> {
  try {
    const response = await fetch(`/api/users/${userId}`);

    if (!response.ok) {
      throw new Error(`HTTP ${response.status}: ${response.statusText}`);
    }

    return await response.json();
  } catch (error) {
    console.error("Failed to fetch user data:", error);
    throw new UserFetchError("Unable to load user data", { cause: error });
  }
}

3. Prop Drilling

// ❌ Bad: Prop drilling through multiple levels
function App() {
  const [user, setUser] = useState<User | null>(null);
  return <Layout user={user} setUser={setUser} />;
}

function Layout({ user, setUser }: Props) {
  return <Sidebar user={user} setUser={setUser} />;
}

function Sidebar({ user, setUser }: Props) {
  return <UserMenu user={user} setUser={setUser} />;
}

// ✅ Good: Use context or state management
const UserContext = createContext<UserContextType | null>(null);

function App() {
  const [user, setUser] = useState<User | null>(null);
  return (
    <UserContext.Provider value={{ user, setUser }}>
      <Layout />
    </UserContext.Provider>
  );
}

function UserMenu() {
  const { user, setUser } = useUser(); // Custom hook
  // ...
}

4. Missing TypeScript Types

// ❌ Bad: Using `any`
function processData(data: any) {
  return data.map((item: any) => item.value);
}

// ✅ Good: Proper typing
interface DataItem {
  id: string;
  value: number;
}

function processData(data: DataItem[]): number[] {
  return data.map((item) => item.value);
}

5. Inefficient Re-renders

// ❌ Bad: Creates new object on every render
function UserList() {
  const style = { color: "blue" }; // New object each render
  return <div style={style}>...</div>;
}

// ✅ Good: Memoize or use constant
const STYLE = { color: "blue" };

function UserList() {
  return <div style={STYLE}>...</div>;
}

// Or use useMemo for dynamic values
function UserList({ darkMode }: Props) {
  const style = useMemo(() => ({ color: darkMode ? "white" : "black" }), [darkMode]);
  return <div style={style}>...</div>;
}

2.5 Review Response Time Expectations

If review is delayed:

• Ping reviewer in Slack after expected time
• Escalate to tech lead after maximum time
• Consider splitting large PRs into smaller chunks

3. Testing Requirements

3.1 Testing Philosophy

Test Pyramid:

       /\
      /  \     E2E Tests (10%)
     /____\
    /      \
   /        \  Integration Tests (30%)
  /__________\
 /            \
/______________\ Unit Tests (60%)

Coverage Requirements:

• Overall: 80% minimum
• New code: 90% minimum
• Critical paths: 100% (auth, payments, PHI handling)
• Utilities: 95% minimum

3.2 Unit Testing

Unit Test Guidelines

File Naming:

• Test files: ComponentName.test.tsx or functionName.test.ts
• Test utilities: test-utils.ts
• Mocks: __mocks__/moduleName.ts

Test Structure:

// src/components/Button.test.tsx
import { describe, it, expect, vi } from "vitest";
import { render, screen, fireEvent } from "@testing-library/react";
import { Button } from "./Button";

describe("Button", () => {
  describe("Rendering", () => {
    it("renders with correct text", () => {
      render(<Button>Click me</Button>);
      expect(screen.getByRole("button", { name: "Click me" })).toBeInTheDocument();
    });

    it("renders with loading state", () => {
      render(<Button loading>Click me</Button>);
      expect(screen.getByRole("button")).toHaveAttribute("disabled");
      expect(screen.getByTestId("spinner")).toBeInTheDocument();
    });

    it("applies variant styles correctly", () => {
      const { rerender } = render(<Button variant="primary">Primary</Button>);
      expect(screen.getByRole("button")).toHaveClass("bg-blue-600");

      rerender(<Button variant="secondary">Secondary</Button>);
      expect(screen.getByRole("button")).toHaveClass("bg-gray-600");
    });
  });

  describe("Interactions", () => {
    it("calls onClick handler when clicked", () => {
      const handleClick = vi.fn();
      render(<Button onClick={handleClick}>Click me</Button>);

      fireEvent.click(screen.getByRole("button"));

      expect(handleClick).toHaveBeenCalledTimes(1);
    });

    it("does not call onClick when disabled", () => {
      const handleClick = vi.fn();
      render(
        <Button onClick={handleClick} disabled>
          Click me
        </Button>,
      );

      fireEvent.click(screen.getByRole("button"));

      expect(handleClick).not.toHaveBeenCalled();
    });
  });

  describe("Accessibility", () => {
    it("has correct ARIA attributes", () => {
      render(<Button aria-label="Close dialog">×</Button>);
      expect(screen.getByLabelText("Close dialog")).toBeInTheDocument();
    });

    it("is keyboard accessible", () => {
      const handleClick = vi.fn();
      render(<Button onClick={handleClick}>Click me</Button>);

      const button = screen.getByRole("button");
      button.focus();

      expect(button).toHaveFocus();

      fireEvent.keyDown(button, { key: "Enter" });
      expect(handleClick).toHaveBeenCalled();
    });
  });

  describe("Edge Cases", () => {
    it("handles rapid clicks gracefully", () => {
      const handleClick = vi.fn();
      render(<Button onClick={handleClick}>Click me</Button>);

      const button = screen.getByRole("button");

      // Simulate rapid clicks
      for (let i = 0; i < 10; i++) {
        fireEvent.click(button);
      }

      expect(handleClick).toHaveBeenCalledTimes(10);
    });
  });
});

Custom Hook Testing

// src/hooks/useAuth.test.ts
import { renderHook, act, waitFor } from "@testing-library/react";
import { describe, it, expect, vi, beforeEach } from "vitest";
import { useAuth } from "./useAuth";
import { authApi } from "@voiceassist/api-client";

vi.mock("@voiceassist/api-client");

describe("useAuth", () => {
  beforeEach(() => {
    vi.clearAllMocks();
  });

  it("initializes with null user", () => {
    const { result } = renderHook(() => useAuth());

    expect(result.current.user).toBeNull();
    expect(result.current.isAuthenticated).toBe(false);
    expect(result.current.isLoading).toBe(false);
  });

  it("logs in successfully", async () => {
    const mockUser = { id: "1", email: "test@example.com" };
    vi.mocked(authApi.login).mockResolvedValue({
      user: mockUser,
      token: "mock-token",
    });

    const { result } = renderHook(() => useAuth());

    act(() => {
      result.current.login("test@example.com", "password");
    });

    expect(result.current.isLoading).toBe(true);

    await waitFor(() => {
      expect(result.current.isLoading).toBe(false);
      expect(result.current.user).toEqual(mockUser);
      expect(result.current.isAuthenticated).toBe(true);
    });
  });

  it("handles login error", async () => {
    const mockError = new Error("Invalid credentials");
    vi.mocked(authApi.login).mockRejectedValue(mockError);

    const { result } = renderHook(() => useAuth());

    await act(async () => {
      await result.current.login("test@example.com", "wrong-password");
    });

    expect(result.current.error).toEqual(mockError);
    expect(result.current.isAuthenticated).toBe(false);
  });

  it("logs out successfully", async () => {
    const { result } = renderHook(() => useAuth());

    // First login
    await act(async () => {
      await result.current.login("test@example.com", "password");
    });

    // Then logout
    act(() => {
      result.current.logout();
    });

    expect(result.current.user).toBeNull();
    expect(result.current.isAuthenticated).toBe(false);
  });
});

Utility Function Testing

// src/utils/date.test.ts
import { describe, it, expect } from "vitest";
import { formatDate, parseDate, isValidDate } from "./date";

describe("Date Utilities", () => {
  describe("formatDate", () => {
    it("formats date in default format", () => {
      const date = new Date("2025-01-15T10:30:00Z");
      expect(formatDate(date)).toBe("Jan 15, 2025");
    });

    it("formats date with custom format", () => {
      const date = new Date("2025-01-15T10:30:00Z");
      expect(formatDate(date, "yyyy-MM-dd")).toBe("2025-01-15");
    });

    it("handles invalid date", () => {
      expect(formatDate(new Date("invalid"))).toBe("Invalid Date");
    });
  });

  describe("parseDate", () => {
    it("parses ISO date string", () => {
      const result = parseDate("2025-01-15T10:30:00Z");
      expect(result).toBeInstanceOf(Date);
      expect(result.getFullYear()).toBe(2025);
    });

    it("returns null for invalid date string", () => {
      expect(parseDate("not-a-date")).toBeNull();
    });
  });

  describe("isValidDate", () => {
    it("returns true for valid date", () => {
      expect(isValidDate(new Date("2025-01-15"))).toBe(true);
    });

    it("returns false for invalid date", () => {
      expect(isValidDate(new Date("invalid"))).toBe(false);
    });

    it("returns false for non-date values", () => {
      expect(isValidDate("2025-01-15")).toBe(false);
      expect(isValidDate(null)).toBe(false);
      expect(isValidDate(undefined)).toBe(false);
    });
  });
});

3.3 Integration Testing

API Integration Tests

// src/api/auth.integration.test.ts
import { describe, it, expect, beforeAll, afterAll } from "vitest";
import { setupServer } from "msw/node";
import { http, HttpResponse } from "msw";
import { authApi } from "@voiceassist/api-client";

const server = setupServer();

beforeAll(() => server.listen());
afterAll(() => server.close());

describe("Auth API Integration", () => {
  it("successfully logs in user", async () => {
    server.use(
      http.post("/api/auth/login", () => {
        return HttpResponse.json({
          user: { id: "1", email: "test@example.com" },
          token: "mock-jwt-token",
          refreshToken: "mock-refresh-token",
        });
      }),
    );

    const result = await authApi.login({
      email: "test@example.com",
      password: "password123",
    });

    expect(result.user).toMatchObject({
      id: "1",
      email: "test@example.com",
    });
    expect(result.token).toBe("mock-jwt-token");
  });

  it("handles 401 authentication error", async () => {
    server.use(
      http.post("/api/auth/login", () => {
        return new HttpResponse(null, {
          status: 401,
          statusText: "Unauthorized",
        });
      }),
    );

    await expect(
      authApi.login({
        email: "test@example.com",
        password: "wrong-password",
      }),
    ).rejects.toThrow("Unauthorized");
  });

  it("refreshes token successfully", async () => {
    server.use(
      http.post("/api/auth/refresh", () => {
        return HttpResponse.json({
          token: "new-jwt-token",
          refreshToken: "new-refresh-token",
        });
      }),
    );

    const result = await authApi.refreshToken("old-refresh-token");

    expect(result.token).toBe("new-jwt-token");
    expect(result.refreshToken).toBe("new-refresh-token");
  });
});

Component Integration Tests

// src/features/auth/LoginPage.integration.test.tsx
import { describe, it, expect, vi } from "vitest";
import { render, screen, waitFor } from "@testing-library/react";
import userEvent from "@testing-library/user-event";
import { LoginPage } from "./LoginPage";
import { QueryClientProvider, QueryClient } from "@tanstack/react-query";
import { BrowserRouter } from "react-router-dom";

const queryClient = new QueryClient({
  defaultOptions: {
    queries: { retry: false },
    mutations: { retry: false },
  },
});

function renderLoginPage() {
  return render(
    <QueryClientProvider client={queryClient}>
      <BrowserRouter>
        <LoginPage />
      </BrowserRouter>
    </QueryClientProvider>,
  );
}

describe("LoginPage Integration", () => {
  it("completes full login flow", async () => {
    const user = userEvent.setup();
    renderLoginPage();

    // Fill in email
    const emailInput = screen.getByLabelText(/email/i);
    await user.type(emailInput, "test@example.com");

    // Fill in password
    const passwordInput = screen.getByLabelText(/password/i);
    await user.type(passwordInput, "password123");

    // Submit form
    const submitButton = screen.getByRole("button", { name: /log in/i });
    await user.click(submitButton);

    // Verify loading state
    expect(screen.getByText(/logging in/i)).toBeInTheDocument();

    // Verify redirect after successful login
    await waitFor(() => {
      expect(window.location.pathname).toBe("/dashboard");
    });
  });

  it("shows validation errors", async () => {
    const user = userEvent.setup();
    renderLoginPage();

    // Submit empty form
    const submitButton = screen.getByRole("button", { name: /log in/i });
    await user.click(submitButton);

    // Verify validation messages
    expect(screen.getByText(/email is required/i)).toBeInTheDocument();
    expect(screen.getByText(/password is required/i)).toBeInTheDocument();
  });

  it("displays API error message", async () => {
    const user = userEvent.setup();
    renderLoginPage();

    // Fill in invalid credentials
    await user.type(screen.getByLabelText(/email/i), "test@example.com");
    await user.type(screen.getByLabelText(/password/i), "wrong-password");

    // Submit form
    await user.click(screen.getByRole("button", { name: /log in/i }));

    // Verify error message
    await waitFor(() => {
      expect(screen.getByText(/invalid credentials/i)).toBeInTheDocument();
    });
  });
});

3.4 End-to-End (E2E) Testing

Playwright E2E Tests

// e2e/auth.spec.ts
import { test, expect } from "@playwright/test";

test.describe("Authentication Flow", () => {
  test("user can log in successfully", async ({ page }) => {
    await page.goto("/login");

    // Fill login form
    await page.fill('input[name="email"]', "test@example.com");
    await page.fill('input[name="password"]', "password123");

    // Submit
    await page.click('button:has-text("Log In")');

    // Verify redirect to dashboard
    await expect(page).toHaveURL("/dashboard");

    // Verify user menu shows
    await expect(page.locator('[data-testid="user-menu"]')).toBeVisible();
    await expect(page.locator('[data-testid="user-email"]')).toHaveText("test@example.com");
  });

  test("shows error for invalid credentials", async ({ page }) => {
    await page.goto("/login");

    await page.fill('input[name="email"]', "test@example.com");
    await page.fill('input[name="password"]', "wrong-password");

    await page.click('button:has-text("Log In")');

    // Verify error message
    await expect(page.locator('[role="alert"]')).toContainText("Invalid credentials");

    // Verify still on login page
    await expect(page).toHaveURL("/login");
  });

  test("user can log out", async ({ page, context }) => {
    // Login first
    await page.goto("/login");
    await page.fill('input[name="email"]', "test@example.com");
    await page.fill('input[name="password"]', "password123");
    await page.click('button:has-text("Log In")');
    await expect(page).toHaveURL("/dashboard");

    // Open user menu
    await page.click('[data-testid="user-menu-button"]');

    // Click logout
    await page.click('button:has-text("Log Out")');

    // Verify redirect to login
    await expect(page).toHaveURL("/login");

    // Verify token cleared
    const cookies = await context.cookies();
    expect(cookies.find((c) => c.name === "auth_token")).toBeUndefined();
  });
});

Voice Mode E2E Tests

// e2e/voice-mode.spec.ts
import { test, expect } from "@playwright/test";

test.describe("Voice Mode", () => {
  test.beforeEach(async ({ page }) => {
    // Login
    await page.goto("/login");
    await page.fill('input[name="email"]', "test@example.com");
    await page.fill('input[name="password"]', "password123");
    await page.click('button:has-text("Log In")');
    await expect(page).toHaveURL("/dashboard");
  });

  test("starts voice session", async ({ page, context }) => {
    // Grant microphone permission
    await context.grantPermissions(["microphone"]);

    await page.goto("/voice");

    // Click start button
    await page.click('button:has-text("Start Voice Mode")');

    // Verify voice mode is active
    await expect(page.locator('[data-testid="voice-status"]')).toHaveText("Listening...");
    await expect(page.locator('[data-testid="voice-indicator"]')).toBeVisible();

    // Verify WebSocket connection
    const wsMessages = [];
    page.on("websocket", (ws) => {
      ws.on("framereceived", (frame) => {
        const data = JSON.parse(frame.payload.toString());
        wsMessages.push(data);
      });
    });

    await page.waitForTimeout(1000);

    expect(wsMessages).toContainEqual(expect.objectContaining({ type: "voice_session_started" }));
  });

  test("displays transcript in real-time", async ({ page, context }) => {
    await context.grantPermissions(["microphone"]);

    await page.goto("/voice");
    await page.click('button:has-text("Start Voice Mode")');

    // Mock WebSocket message
    await page.evaluate(() => {
      // Simulate transcript message
      window.dispatchEvent(
        new CustomEvent("ws-message", {
          detail: {
            type: "transcript",
            text: "What is hypertension?",
            isFinal: true,
          },
        }),
      );
    });

    // Verify transcript appears
    await expect(page.locator('[data-testid="transcript"]')).toContainText("What is hypertension?");
  });

  test("stops voice session", async ({ page, context }) => {
    await context.grantPermissions(["microphone"]);

    await page.goto("/voice");
    await page.click('button:has-text("Start Voice Mode")');

    await expect(page.locator('[data-testid="voice-status"]')).toHaveText("Listening...");

    // Stop voice mode
    await page.click('button:has-text("Stop")');

    // Verify stopped
    await expect(page.locator('[data-testid="voice-status"]')).toHaveText("Stopped");
    await expect(page.locator('[data-testid="voice-indicator"]')).not.toBeVisible();
  });
});

3.5 Accessibility Testing

// src/components/Button.a11y.test.tsx
import { describe, it, expect } from "vitest";
import { render } from "@testing-library/react";
import { axe, toHaveNoViolations } from "jest-axe";
import { Button } from "./Button";

expect.extend(toHaveNoViolations);

describe("Button Accessibility", () => {
  it("has no accessibility violations", async () => {
    const { container } = render(<Button>Click me</Button>);
    const results = await axe(container);
    expect(results).toHaveNoViolations();
  });

  it("has no violations when disabled", async () => {
    const { container } = render(<Button disabled>Click me</Button>);
    const results = await axe(container);
    expect(results).toHaveNoViolations();
  });

  it("has no violations with icon only", async () => {
    const { container } = render(
      <Button aria-label="Close">
        <CloseIcon />
      </Button>,
    );
    const results = await axe(container);
    expect(results).toHaveNoViolations();
  });

  it("maintains focus visibility", () => {
    const { getByRole } = render(<Button>Click me</Button>);
    const button = getByRole("button");

    button.focus();

    // Check for visible focus indicator
    const styles = window.getComputedStyle(button);
    expect(styles.outline).not.toBe("none");
  });

  it("supports keyboard navigation", () => {
    const handleClick = vi.fn();
    const { getByRole } = render(<Button onClick={handleClick}>Click me</Button>);
    const button = getByRole("button");

    // Enter key
    fireEvent.keyDown(button, { key: "Enter" });
    expect(handleClick).toHaveBeenCalled();

    // Space key
    fireEvent.keyDown(button, { key: " " });
    expect(handleClick).toHaveBeenCalledTimes(2);
  });
});

3.6 Performance Testing

// src/components/ChatMessageList.perf.test.tsx
import { describe, it, expect } from "vitest";
import { render } from "@testing-library/react";
import { ChatMessageList } from "./ChatMessageList";

describe("ChatMessageList Performance", () => {
  it("renders 1000 messages in under 500ms", () => {
    const messages = Array.from({ length: 1000 }, (_, i) => ({
      id: String(i),
      text: `Message ${i}`,
      sender: i % 2 === 0 ? "user" : "assistant",
      timestamp: new Date(),
    }));

    const startTime = performance.now();
    render(<ChatMessageList messages={messages} />);
    const endTime = performance.now();

    const renderTime = endTime - startTime;
    expect(renderTime).toBeLessThan(500);
  });

  it("does not re-render when unrelated props change", () => {
    const messages = [{ id: "1", text: "Hello", sender: "user", timestamp: new Date() }];

    let renderCount = 0;
    const TestComponent = () => {
      renderCount++;
      return <ChatMessageList messages={messages} />;
    };

    const { rerender } = render(<TestComponent />);
    expect(renderCount).toBe(1);

    // Rerender with same messages
    rerender(<TestComponent />);
    expect(renderCount).toBe(1); // Should not re-render
  });
});