test: Add integration tests for task import functions (beads, GitHub Issues)

[frankbria]

Summary

The task import functions in lib/task_sources.sh lack integration tests for the actual import logic. Current tests only verify detection (whether tools are available) but skip testing the parsing and import functionality.

Current Test Gap Analysis

Function	Current Tests	Gap
fetch_beads_tasks()	0	No tests - JSON parsing, text fallback, status filtering untested
fetch_github_tasks()	0	No tests - JSON parsing, label filtering untested
get_beads_count()	1	Only tests unavailable case, not actual counting
get_github_issue_count()	1	Only tests unavailable case, not actual counting
import_tasks_from_sources()	1	Only tests PRD source, not beads/github sources

Context

PR #150 fixed several bugs in fetch_beads_tasks():

• Fixed bd list arguments (non-existent --filter flag)
• Fixed jq != bash escaping issue
• Added status-respecting fallback for text parsing
• Added jq guards for missing id/title fields

These fixes were only manually tested. Integration tests would prevent regressions.

Proposed Tests

1. Beads Import Tests (fetch_beads_tasks)

# Test JSON parsing with mocked bd command
@test "fetch_beads_tasks parses JSON output correctly" {
    # Mock bd to return JSON
    bd() { echo '[{"id":"proj-001","title":"Fix bug","status":"open"}]'; }
    export -f bd
    ...
}

# Test text fallback parsing
@test "fetch_beads_tasks falls back to text parsing when JSON fails" {
    # Mock bd to return text format
    bd() { echo "○ proj-001 [● P2] [task] - Fix authentication bug"; }
    ...
}

# Test status filtering
@test "fetch_beads_tasks respects filterStatus parameter" { ... }

# Test empty results
@test "fetch_beads_tasks handles empty JSON array" { ... }

# Test malformed JSON fallback
@test "fetch_beads_tasks falls back to text on malformed JSON" { ... }

# Test missing fields (jq guards)
@test "fetch_beads_tasks filters entries with missing id" { ... }
@test "fetch_beads_tasks filters entries with missing title" { ... }

2. GitHub Import Tests (fetch_github_tasks)

# Test JSON parsing
@test "fetch_github_tasks parses issue JSON correctly" {
    # Mock gh to return JSON
    gh() { echo '[{"number":123,"title":"Add feature"}]'; }
    ...
}

# Test label filtering
@test "fetch_github_tasks filters by label" { ... }

# Test limit parameter
@test "fetch_github_tasks respects limit parameter" { ... }

# Test empty results
@test "fetch_github_tasks handles no matching issues" { ... }

3. Combined Import Tests (import_tasks_from_sources)

# Test beads source
@test "import_tasks_from_sources imports from beads" { ... }

# Test github source  
@test "import_tasks_from_sources imports from github" { ... }

# Test multiple sources
@test "import_tasks_from_sources combines beads and github" { ... }

4. Count Function Tests

@test "get_beads_count returns correct count from JSON" { ... }
@test "get_github_issue_count returns correct count" { ... }

Implementation Approach

1. Create mock command helpers in tests/helpers/:

   • mock_bd() - Returns configurable JSON/text output
   • mock_gh() - Returns configurable issue JSON

2. Add fixture data in tests/helpers/fixtures.bash:

   • Sample beads JSON responses
   • Sample beads text output
   • Sample GitHub issue JSON

3. Create test file: tests/integration/test_task_imports.bats

Acceptance Criteria

• fetch_beads_tasks() has tests for JSON parsing, text fallback, status filtering, and edge cases
• fetch_github_tasks() has tests for JSON parsing, label filtering, and edge cases
• import_tasks_from_sources() tested with beads and github sources
• Count functions tested with actual data
• All tests use mocked commands (no external dependencies)
• Tests cover the PR fix: beads task import uses correct bd list arguments #150 fixes to prevent regression

Labels

• testing
• enhancement
• good first issue

Related

• PR fix: beads task import uses correct bd list arguments #150 - fix: beads task import uses correct bd list arguments
• lib/task_sources.sh - Source file under test
• tests/unit/test_task_sources.bats - Existing unit tests

[traycerai]

Plan

Observations

The codebase uses BATS (Bash Automated Testing System) for testing with a well-established pattern. Current tests in file:tests/unit/test_task_sources.bats only verify detection (whether tools are available) but skip actual import logic testing. The source file file:lib/task_sources.sh contains PR #150 fixes including jq guards for missing fields, status-respecting fallback parsing, and proper bd list arguments. The test infrastructure provides helpers in file:tests/helpers/test_helper.bash and fixtures in file:tests/helpers/fixtures.bash, with inline mock patterns demonstrated in file:tests/integration/test_prd_import.bats.

Approach

Create integration tests using inline mock functions (following the existing pattern from test_prd_import.bats) rather than separate mock helpers. Add fixture data generators to fixtures.bash for beads and GitHub JSON responses. Create a new integration test file that mocks the bd and gh commands to return controlled output, then verifies the parsing, filtering, and import logic. This approach ensures the PR #150 fixes are tested and prevents regressions while maintaining consistency with the existing test infrastructure.

Implementation Steps

1. Add Fixture Data to file:tests/helpers/fixtures.bash

Add the following fixture generator functions at the end of the file:

Beads JSON Fixtures:

• create_sample_beads_json() - Returns valid beads JSON with multiple tasks including different statuses (open, in_progress, closed), priorities, and task types
• create_sample_beads_json_empty() - Returns empty JSON array []
• create_sample_beads_json_malformed() - Returns invalid JSON to test fallback behavior
• create_sample_beads_json_missing_fields() - Returns JSON with entries missing id or title fields to test jq guards

Beads Text Output Fixtures:

• create_sample_beads_text() - Returns text format matching bd list output: ○ proj-001 [● P2] [task] - Fix authentication bug
• Include multiple lines with different statuses and formats

GitHub JSON Fixtures:

• create_sample_github_json() - Returns valid GitHub issues JSON with number, title, and labels fields
• create_sample_github_json_empty() - Returns empty JSON array
• create_sample_github_json_with_labels() - Returns issues with specific labels for filtering tests

2. Create Integration Test File file:tests/integration/test_task_imports.bats

File Structure:

#!/usr/bin/env bats
# Integration tests for task import functions
# Tests beads, GitHub Issues, and combined import logic

load '../helpers/test_helper'
load '../helpers/fixtures'

TASK_SOURCES="${BATS_TEST_DIRNAME}/../../lib/task_sources.sh"

Setup/Teardown:

• Create temporary test directory
• Source task_sources.sh
• Set up mock PATH to intercept bd and gh commands
• Clean up in teardown

3. Implement Beads Import Tests (8 tests)

Mock bd Command Pattern:
Create inline mock function in each test that exports to override the real command:

bd() { echo '[{"id":"proj-001","title":"Fix bug","status":"open"}]'; }
export -f bd

Test Cases:

JSON Parsing Tests:

• fetch_beads_tasks parses JSON output correctly - Mock bd to return valid JSON, verify markdown checkbox format output
• fetch_beads_tasks filters entries with missing id field - Mock JSON with missing id, verify those entries are excluded
• fetch_beads_tasks filters entries with missing title field - Mock JSON with missing title, verify exclusion
• fetch_beads_tasks handles empty JSON array - Mock empty array, verify success with no output

Text Fallback Tests:

• fetch_beads_tasks falls back to text parsing when JSON fails - Mock bd to fail on --json but succeed on text, verify fallback works
• fetch_beads_tasks text fallback respects status filter - Mock text output, verify status filtering in fallback mode

Status Filtering Tests:

• fetch_beads_tasks filters by open status - Mock JSON with mixed statuses, call with filterStatus="open", verify only open tasks
• fetch_beads_tasks filters by in_progress status - Similar test for in_progress filter

4. Implement GitHub Import Tests (6 tests)

Mock gh Command Pattern:

gh() {
  if [[ "$*" == *"--json"* ]]; then
    echo '[{"number":123,"title":"Add feature","labels":[]}]'
  fi
}
export -f gh

Test Cases:

JSON Parsing Tests:

• fetch_github_tasks parses issue JSON correctly - Mock gh to return valid JSON, verify markdown format with [#123] prefix
• fetch_github_tasks handles empty results - Mock empty array, verify success with no output

Label Filtering Tests:

• fetch_github_tasks filters by label - Mock gh, verify --label argument is passed correctly
• fetch_github_tasks works without label filter - Call without label parameter, verify no --label in command

Limit Parameter Tests:

• fetch_github_tasks respects limit parameter - Mock gh, verify --limit argument matches parameter
• fetch_github_tasks uses default limit of 50 - Call without limit, verify default is used

5. Implement Combined Import Tests (4 tests)

Test Cases:

• import_tasks_from_sources imports from beads only - Mock bd, call with sources="beads", verify beads tasks in output
• import_tasks_from_sources imports from github only - Mock gh, call with sources="github", verify GitHub tasks in output
• import_tasks_from_sources combines beads and github - Mock both commands, call with sources="beads github", verify both sections appear in output
• import_tasks_from_sources normalizes combined output - Verify output goes through normalize_tasks() function

6. Implement Count Function Tests (4 tests)

Test Cases:

• get_beads_count returns correct count from JSON - Mock bd to return JSON with 3 tasks, verify count is 3
• get_beads_count filters closed tasks from count - Mock JSON with mixed statuses, verify only non-closed counted
• get_github_issue_count returns correct count - Mock gh to return JSON with 5 issues, verify count is 5
• get_github_issue_count respects label filter - Mock gh, call with label parameter, verify --label passed to command

7. Test PR #150 Regression Prevention (3 tests)

Specific Tests for Fixed Bugs:

• fetch_beads_tasks uses correct bd list arguments - Verify --status flag is used instead of non-existent --filter
• fetch_beads_tasks jq handles != operator correctly - Verify select(.status == "closed" | not) pattern instead of != "closed"
• fetch_beads_tasks jq guards handle missing fields - Verify select((.id // "") != "") pattern works

8. Verification and Documentation

Test Execution:

• Run new test file: bats tests/integration/test_task_imports.bats
• Verify all tests pass
• Run full test suite: npm test
• Ensure no regressions in existing tests

Coverage Verification:

• Confirm all functions mentioned in ticket have tests:
  • fetch_beads_tasks() ✓
  • fetch_github_tasks() ✓
  • get_beads_count() ✓
  • get_github_issue_count() ✓
  • import_tasks_from_sources() ✓

Documentation:

• Update file:TESTING.md test count (currently 276 tests, will increase by ~25)
• Add entry to test organization section mentioning test_task_imports.bats

Test Structure Diagram

sequenceDiagram
    participant Test as BATS Test
    participant Mock as Mock bd/gh
    participant Source as task_sources.sh
    participant Output as Assertions

    Test->>Mock: Define mock function
    Test->>Mock: export -f bd/gh
    Test->>Source: Call fetch_beads_tasks()
    Source->>Mock: Execute bd list --json
    Mock-->>Source: Return fixture JSON
    Source->>Source: Parse with jq
    Source-->>Test: Return markdown tasks
    Test->>Output: assert_success
    Test->>Output: Verify output format

Loading

Key Testing Patterns

Pattern	Usage	Example
Inline Mocks	Override commands in test scope	bd() { echo '[]'; }; export -f bd
Fixture Data	Reusable test data	create_sample_beads_json
Status Verification	Check exit codes	assert_success / assert_failure
Output Matching	Verify content	[[ "$output" =~ "expected" ]]
Argument Capture	Verify command args	Check mock receives correct flags

Import In IDE

🤖 Prompt for AI Agents

## Observations

The codebase uses BATS (Bash Automated Testing System) for testing with a well-established pattern. Current tests in `file:tests/unit/test_task_sources.bats` only verify detection (whether tools are available) but skip actual import logic testing. The source file `file:lib/task_sources.sh` contains PR #150 fixes including jq guards for missing fields, status-respecting fallback parsing, and proper `bd list` arguments. The test infrastructure provides helpers in `file:tests/helpers/test_helper.bash` and fixtures in `file:tests/helpers/fixtures.bash`, with inline mock patterns demonstrated in `file:tests/integration/test_prd_import.bats`.

## Approach

Create integration tests using inline mock functions (following the existing pattern from `test_prd_import.bats`) rather than separate mock helpers. Add fixture data generators to `fixtures.bash` for beads and GitHub JSON responses. Create a new integration test file that mocks the `bd` and `gh` commands to return controlled output, then verifies the parsing, filtering, and import logic. This approach ensures the PR #150 fixes are tested and prevents regressions while maintaining consistency with the existing test infrastructure.

## Implementation Steps

### 1. Add Fixture Data to `file:tests/helpers/fixtures.bash`

Add the following fixture generator functions at the end of the file:

**Beads JSON Fixtures:**
- `create_sample_beads_json()` - Returns valid beads JSON with multiple tasks including different statuses (open, in_progress, closed), priorities, and task types
- `create_sample_beads_json_empty()` - Returns empty JSON array `[]`
- `create_sample_beads_json_malformed()` - Returns invalid JSON to test fallback behavior
- `create_sample_beads_json_missing_fields()` - Returns JSON with entries missing `id` or `title` fields to test jq guards

**Beads Text Output Fixtures:**
- `create_sample_beads_text()` - Returns text format matching `bd list` output: `○ proj-001 [● P2] [task] - Fix authentication bug`
- Include multiple lines with different statuses and formats

**GitHub JSON Fixtures:**
- `create_sample_github_json()` - Returns valid GitHub issues JSON with `number`, `title`, and `labels` fields
- `create_sample_github_json_empty()` - Returns empty JSON array
- `create_sample_github_json_with_labels()` - Returns issues with specific labels for filtering tests

### 2. Create Integration Test File `file:tests/integration/test_task_imports.bats`

**File Structure:**
```
#!/usr/bin/env bats
# Integration tests for task import functions
# Tests beads, GitHub Issues, and combined import logic

load '../helpers/test_helper'
load '../helpers/fixtures'

TASK_SOURCES="${BATS_TEST_DIRNAME}/../../lib/task_sources.sh"
```

**Setup/Teardown:**
- Create temporary test directory
- Source `task_sources.sh`
- Set up mock PATH to intercept `bd` and `gh` commands
- Clean up in teardown

### 3. Implement Beads Import Tests (8 tests)

**Mock `bd` Command Pattern:**
Create inline mock function in each test that exports to override the real command:
```bash
bd() { echo '[{"id":"proj-001","title":"Fix bug","status":"open"}]'; }
export -f bd
```

**Test Cases:**

**JSON Parsing Tests:**
- `fetch_beads_tasks parses JSON output correctly` - Mock `bd` to return valid JSON, verify markdown checkbox format output
- `fetch_beads_tasks filters entries with missing id field` - Mock JSON with missing `id`, verify those entries are excluded
- `fetch_beads_tasks filters entries with missing title field` - Mock JSON with missing `title`, verify exclusion
- `fetch_beads_tasks handles empty JSON array` - Mock empty array, verify success with no output

**Text Fallback Tests:**
- `fetch_beads_tasks falls back to text parsing when JSON fails` - Mock `bd` to fail on `--json` but succeed on text, verify fallback works
- `fetch_beads_tasks text fallback respects status filter` - Mock text output, verify status filtering in fallback mode

**Status Filtering Tests:**
- `fetch_beads_tasks filters by open status` - Mock JSON with mixed statuses, call with `filterStatus="open"`, verify only open tasks
- `fetch_beads_tasks filters by in_progress status` - Similar test for in_progress filter

### 4. Implement GitHub Import Tests (6 tests)

**Mock `gh` Command Pattern:**
```bash
gh() {
  if [[ "$*" == *"--json"* ]]; then
    echo '[{"number":123,"title":"Add feature","labels":[]}]'
  fi
}
export -f gh
```

**Test Cases:**

**JSON Parsing Tests:**
- `fetch_github_tasks parses issue JSON correctly` - Mock `gh` to return valid JSON, verify markdown format with `[#123]` prefix
- `fetch_github_tasks handles empty results` - Mock empty array, verify success with no output

**Label Filtering Tests:**
- `fetch_github_tasks filters by label` - Mock `gh`, verify `--label` argument is passed correctly
- `fetch_github_tasks works without label filter` - Call without label parameter, verify no `--label` in command

**Limit Parameter Tests:**
- `fetch_github_tasks respects limit parameter` - Mock `gh`, verify `--limit` argument matches parameter
- `fetch_github_tasks uses default limit of 50` - Call without limit, verify default is used

### 5. Implement Combined Import Tests (4 tests)

**Test Cases:**

- `import_tasks_from_sources imports from beads only` - Mock `bd`, call with `sources="beads"`, verify beads tasks in output
- `import_tasks_from_sources imports from github only` - Mock `gh`, call with `sources="github"`, verify GitHub tasks in output
- `import_tasks_from_sources combines beads and github` - Mock both commands, call with `sources="beads github"`, verify both sections appear in output
- `import_tasks_from_sources normalizes combined output` - Verify output goes through `normalize_tasks()` function

### 6. Implement Count Function Tests (4 tests)

**Test Cases:**

- `get_beads_count returns correct count from JSON` - Mock `bd` to return JSON with 3 tasks, verify count is 3
- `get_beads_count filters closed tasks from count` - Mock JSON with mixed statuses, verify only non-closed counted
- `get_github_issue_count returns correct count` - Mock `gh` to return JSON with 5 issues, verify count is 5
- `get_github_issue_count respects label filter` - Mock `gh`, call with label parameter, verify `--label` passed to command

### 7. Test PR #150 Regression Prevention (3 tests)

**Specific Tests for Fixed Bugs:**

- `fetch_beads_tasks uses correct bd list arguments` - Verify `--status` flag is used instead of non-existent `--filter`
- `fetch_beads_tasks jq handles != operator correctly` - Verify `select(.status == "closed" | not)` pattern instead of `!= "closed"`
- `fetch_beads_tasks jq guards handle missing fields` - Verify `select((.id // "") != "")` pattern works

### 8. Verification and Documentation

**Test Execution:**
- Run new test file: `bats tests/integration/test_task_imports.bats`
- Verify all tests pass
- Run full test suite: `npm test`
- Ensure no regressions in existing tests

**Coverage Verification:**
- Confirm all functions mentioned in ticket have tests:
  - `fetch_beads_tasks()` ✓
  - `fetch_github_tasks()` ✓
  - `get_beads_count()` ✓
  - `get_github_issue_count()` ✓
  - `import_tasks_from_sources()` ✓

**Documentation:**
- Update `file:TESTING.md` test count (currently 276 tests, will increase by ~25)
- Add entry to test organization section mentioning `test_task_imports.bats`

## Test Structure Diagram

```mermaid
sequenceDiagram
    participant Test as BATS Test
    participant Mock as Mock bd/gh
    participant Source as task_sources.sh
    participant Output as Assertions

    Test->>Mock: Define mock function
    Test->>Mock: export -f bd/gh
    Test->>Source: Call fetch_beads_tasks()
    Source->>Mock: Execute bd list --json
    Mock-->>Source: Return fixture JSON
    Source->>Source: Parse with jq
    Source-->>Test: Return markdown tasks
    Test->>Output: assert_success
    Test->>Output: Verify output format
```

## Key Testing Patterns

| Pattern | Usage | Example |
|---------|-------|---------|
| **Inline Mocks** | Override commands in test scope | `bd() { echo '[]'; }; export -f bd` |
| **Fixture Data** | Reusable test data | `create_sample_beads_json` |
| **Status Verification** | Check exit codes | `assert_success` / `assert_failure` |
| **Output Matching** | Verify content | `[[ "$output" =~ "expected" ]]` |
| **Argument Capture** | Verify command args | Check mock receives correct flags |

---

Execution Information

Branch: main
Commit: 02dbb07

---

💡 Tips

Supported Commands (Inside Comments)

• Use @traycerai generate to iterate on the previous version of the implementation plan.

Supported Commands (Inside Description)

• Add @traycerai ignore anywhere in the ticket description to prevent this ticket from being processed.
• Add @traycerai branch:<branch-name> anywhere in the ticket description to specify the target branch for the implementation plan.

Community

• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.

[coderabbitai]

📝 CodeRabbit Plan Mode

Generate an implementation plan and prompts that you can use with your favorite coding agent.

• Create Plan

Examples

• Example 1
• Example 2

---

🔗 Related PRs

#59 - test(install): add comprehensive installation tests [merged]
#60 - test(setup): add 36 comprehensive tests for setup.sh [merged]
#61 - test(import): add 22 comprehensive tests for ralph_import.sh [merged]
#124 - feat(enable): add ralph-enable wizard for existing projects (v0.11.0) [merged]
#150 - fix: beads task import uses correct bd list arguments [closed]

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!