bug-fixing-guide

# Bug Fixing Guide

Standard practices for fixing bugs in Composio SDK. Always add regression tests for major bugs.

## Bug Fix Process

### 1. Understand the Bug

- **Reproduce the issue** - Create a minimal reproduction case
- **Identify root cause** - Debug and trace the issue to its source
- **Check existing tests** - See if tests exist for the affected code
- **Review related code** - Check for similar issues elsewhere

### 2. Fix the Bug

- **Implement the fix** - Make minimal changes to address the root cause
- **Avoid scope creep** - Don't refactor unrelated code
- **Follow coding standards** - Maintain consistency with existing code
- **Test locally** - Verify the fix works as expected

### 3. Verify the Fix (Quick Functional Testing)

**Optional but Recommended:** Test actual functionality before adding unit tests.

For bugs affecting framework integrations or real-world usage:

- Use **ephemeral E2E tests** to quickly verify the fix works end-to-end
- Read `ephemeral-e2e-sdk-tests` skill for quick verification setup
- Test in `.agent_cache/test-<bug-description>` (never commit these)
- Example: `.agent_cache/test-fix-openai-tool-execution`

### 4. Add Regression Tests (Required for Major Bugs)

**Critical:** For major bugs, always add tests to prevent regressions.

See `.claude/rules/bug-fix-testing.mdc` for detailed testing requirements:

- Where to add tests (TypeScript: `ts/packages/<package>/test/`, Python: `python/tests/`)
- How to structure tests (Vitest for TS, pytest for Python)
- Test naming conventions and patterns
- Mocking strategies

**Key Points:**

- Add tests to **existing test files** for the affected feature
- Tests should **fail before the fix** and **pass after**
- Cover edge cases related to the bug
- Run tests before committing: `pnpm test` (TS) or `make tst` (Python)

### 5. Document the Fix

- **Clear commit message** - Describe what was fixed and why
- **Reference issues** - Link to GitHub issues or tickets
- **Update docs** - If the bug exposed unclear documentation
- **Add comments** - Explain non-obvious fixes in the code

## When to Add Tests

**Always add tests for:**

- Logic errors and incorrect behavior
- Edge cases and boundary conditions
- Race conditions and async issues
- Security vulnerabilities
- Data corruption or loss issues

**Consider tests for:**

- Type errors (if not caught by TypeScript/mypy)
- Minor UI/UX issues
- Performance optimizations

**May skip tests for:**

- Trivial typo fixes in comments/docs
- Formatting or linting issues

## Testing Resources

- **Quick verification**: Read `ephemeral-e2e-sdk-tests` skill (test in `.agent_cache/`)
- **Full testing guidelines**: `.claude/rules/bug-fix-testing.mdc`
- **TypeScript tests**: `ts/packages/<package>/test/`
- **Python tests**: `python/tests/`
- **E2E tests**: `ts/e2e-tests/` (for runtime compatibility issues)

## Common Pitfalls

- Fixing symptoms instead of root cause
- Not adding regression tests for major bugs
- Breaking existing tests without updating them
- Adding tests in new files instead of existing ones
- Not running the full test suite before committing