Testing

Test your jssg codemod using snapshot testing with input/expected file pairs.

Test structure

jssg tests use a simple directory structure where each test case contains two files:

tests/
  basic-transform/          # Test case directory
    input.ts               # Code before transformation
    expected.ts            # Expected output after transformation
  edge-cases/               # Another test case
    input.tsx
    expected.tsx

File naming:

• Input files must be named input.ts (or appropriate extension)
• Expected files must be named expected.ts (or appropriate extension)
• File extensions should match your target language (.ts, .tsx, .js, .jsx)

Command reference

Basic syntax

npx codemod jssg test -l <language> <codemod-file> [test-directory]

-l, --language · string · required

Language parser to use (e.g., “tsx”, “javascript”, “typescript”).

codemod-file · string · required

Path to your transform file (e.g., ”./scripts/codemod.ts”).

test-directory · string

Path to test directory (defaults to ”./tests”).

Common options

# Update expected outputs when changes are intentional
npx codemod jssg test -l tsx ./scripts/codemod.ts -u

# Run only tests matching a pattern
npx codemod jssg test -l tsx ./scripts/codemod.ts --filter "edge-cases"

# Show detailed output for debugging
npx codemod jssg test -l tsx ./scripts/codemod.ts -v

# Run tests one at a time (helpful for debugging)
npx codemod jssg test -l tsx ./scripts/codemod.ts --sequential

See all available options in the CLI reference.

Creating effective test cases

1. Start simple:

// input.ts
console.log("test");

// expected.ts  
logger.log("test");

2. Add edge cases:

// input.ts
// Should not transform
const preserved = "unchanged";

// Should transform
console.log("transform me");

3. Test different file types:

// input.tsx
function Component() {
  console.log("Hello");
  return <div>World</div>;
}

Understanding test results

Exit codes

• 0: All tests passed
• 1: At least one test failed (diffs are printed)
• 2: Error occurred (e.g., syntax error in codemod)

Reading test output

✓ tests/basic-transform
✗ tests/edge-cases
  Expected: logger.log("test")
  Actual:   console.log("test")

Pro tip: Use -v flag for detailed output when debugging test failures.

Troubleshooting

Language mismatch

Problem: Tests fail with parsing errors.

Solution: Ensure the -l flag matches your source files:

# For TypeScript files
npx codemod jssg test -l typescript ./scripts/codemod.ts

# For TSX files  
npx codemod jssg test -l tsx ./scripts/codemod.ts

# For JavaScript files
npx codemod jssg test -l javascript ./scripts/codemod.ts

Files not found

Problem: “No test files found” error.

Solution: Check your directory structure and file names:

# Verify structure
ls -la tests/basic-transform/
# Should show: input.ts  expected.ts

# Check file names are correct
ls tests/basic-transform/
# Should show: input.ts  expected.ts

Transform not applied

Problem: Test passes but no changes were made.

Solution: This is normal if your transform returns null for unchanged files. If you expect changes:

# Run with verbose output to debug
npx codemod jssg test -l tsx ./scripts/codemod.ts -v

Unexpected diffs

Problem: Test fails with unexpected output.

Solution: Update expected output if changes are intentional:

# Update snapshots
npx codemod jssg test -l tsx ./scripts/codemod.ts -u

Codemod syntax errors

Problem: “Syntax error in codemod” or TypeScript errors.

Solution: Check your transform file:

# Validate TypeScript
npx tsc --noEmit ./scripts/codemod.ts

# Test with a simple file first
echo 'console.log("test");' > test-input.js
npx codemod jssg run -l javascript ./scripts/codemod.ts test-input.js

Workflow integration

Package script

Add to your package.json:

package.json

{
  "scripts": {
    "test": "npx codemod jssg test -l tsx ./scripts/codemod.ts",
    "test:update": "npx codemod jssg test -l tsx ./scripts/codemod.ts -u",
    "test:verbose": "npx codemod jssg test -l tsx ./scripts/codemod.ts -v"
  }
}

CI/CD integration

.github/workflows/test.yml

name: Test Codemod
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '22' # Use current LTS
      - run: npm ci # Do not recreate lockfile; ensures reproducible installs
      - run: npm test

Best practices

• Start simple: Begin with basic transformations before complex ones
• Test edge cases: Include empty files, files with comments, and malformed code
• Use descriptive names: Make test cases self-documenting
• Keep tests focused: One transformation per test case
• Validate locally: Always test before publishing