For specific test by index

moon test -p -f .mbt -i


Document:
- Error messages
- Stack traces
- Expected vs actual behavior
- Steps to reproduce

### 2. Analyze Root Cause

Investigate the error systematically:

**a) Examine error messages**
- Identify the failing component
- Note line numbers and function names

**b) Locate relevant code**
- Use Glob to find implementation files: `**/*<keyword>*.mbt`
- Use Grep to search for specific functions or patterns
- Read source code in relevant modules

**c) For WASM-related bugs**
```bash
./wasmoon explore <file>.wat --stage ir vcode mc

Check IR, VCode, and machine code for issues.

d) For crashes or segfaults

lldb -- ./wasmoon test <file>.wast
(lldb) run
(lldb) bt  # After crash

3. Create Regression Test

Before fixing, write a test that reproduces the bug:

For WASM execution bugs:

test "descriptive_bug_name" {
  let source =
    #|(module
    #|  (func (export "test") (result i32)
    #|    ; Bug-reproducing code here
    #|  )
    #|)
  let result = compare_jit_interp(source, "test", [])
  inspect(result, content="matched")
}

For unit tests:

test "descriptive_bug_name" {
  let result = buggy_function(input)
  inspect(result, content="expected_value")
}

Place the test in the appropriate *_test.mbt file in the relevant package.

Verify the test fails:

moon test -p <package> -f <test_file>.mbt

4. Implement Fix

Make the necessary code changes:

Fix the root cause, not just symptoms
Follow coding standards (see ERRATA.md and CLAUDE.md)
Keep changes minimal and focused
Avoid refactoring unless necessary

Run tests to verify:

moon test -p <package>      # Unit tests
moon test                    # All tests
moon build && ./install.sh  # For wasmoon binary changes

5. Verify No Regressions

Ensure the fix doesn't break other functionality:

moon test                    # All unit tests
python3 scripts/run_all_wast.py --rec  # All wast tests

6. Create Pull Request

a) Create feature branch

git checkout -b fix/<descriptive-name>

b) Commit changes

moon fmt && moon info
git add .
git commit -m "$(cat <<'EOF'
fix: <brief description>

- Root cause: <explanation>
- Solution: <what was changed>
- Test: <test that verifies the fix>

EOF
)"

c) Push and create PR

git push -u origin fix/<descriptive-name>
gh pr create --title "fix: <brief description>" --body "$(cat <<'EOF'
## Summary
- Root cause: <explanation>
- Solution: <what was changed>
- Test: <test file and description>

## Test Plan
- [ ] Regression test passes
- [ ] All existing tests pass
- [ ] Manual verification of fix

EOF
)"

Best Practices

Always create a regression test before fixing
Keep fixes minimal and focused
Test both the fix and potential regressions
Document the root cause in commit messages
Follow project commit message conventions
Never use commit --amend or push --force on shared branches

Command Reference

# Build and install
moon build && ./install.sh

# Run tests
moon test -p <package> -f <file>.mbt
moon test -p <package> -f <file>.mbt -i <index>

# Analyze WASM
./wasmoon explore <file>.wat --stage ir vcode mc
./wasmoon test <file>.wast
./wasmoon test --no-jit <file>.wast

# Debug with LLDB
lldb -- ./wasmoon test <file>.wast

# Git workflow
git checkout -b fix/<name>
git add . && git commit
git push -u origin fix/<name>
gh pr create

fix-bug

Fix Bug Workflow

Workflow

1. Reproduce the Bug