faf-taf-git

Platform-agnostic TAF (Testing Activity Feed) updater - works in ANY CI/CD

Part of the Golden Triangle: .faf (what it is) + repo (implementation) + .taf (proof it works)

🎯 WHAT

faf-taf-git automatically generates .taf receipts from your test runs.

A .taf file is a git-tracked timeline of your testing history:

• Permanent proof of test quality
• Pass rate trends and failure patterns
• Integration with .faf project DNA
• Git-native accountability (no external services required)

Example .taf entry:

- timestamp: 2026-02-17T19:12:14.810Z
  result: PASSED
  tests:
    total: 808
    passed: 799
    failed: 0
    skipped: 9
  trigger: github-actions

👥 WHO

For development teams who need:

• Proof of testing over time (not just current state)
• Git-tracked test accountability (visible in PRs, commits, history)
• AI-readable test context (feeds into .faf project DNA)
• Platform-agnostic testing receipts (works in ANY CI/CD)

Use cases:

• Open source projects (prove your tests pass)
• Regulated industries (auditable test history)
• AI-augmented development (give AI your test timeline)
• Championship engineering (F1-grade accountability)

🤔 WHY

The Problem

Tests run, results disappear. No permanent record. No accountability.

Before:

✅ Tests passing (right now)
❓ Were they passing yesterday?
❓ When did that flaky test start failing?
❓ What's the trend over time?

After (with .taf):

✅ Tests passing (tracked in git)
✅ History shows: 99% pass rate over 30 days
✅ Flaky test identified: started failing Feb 10
✅ Trend: improving (was 85%, now 99%)

The Solution

Git-native receipts. Every test run becomes a permanent, auditable record.

.taf is software accountability - proof that your code works, tracked over time, visible to everyone.

📍 WHERE

Works in ANY CI/CD environment that runs Node.js:

| Platform | Status | Example | |----------|--------|---------| | GitHub Actions | ✅ Tested | See Quick Start | | GitLab CI | ✅ Tested | npx faf-taf-git --commit | | Jenkins | ✅ Compatible | sh 'npx faf-taf-git --commit' | | CircleCI | ✅ Compatible | run: npx faf-taf-git --commit | | Bitbucket Pipelines | ✅ Compatible | npx faf-taf-git --commit | | Travis CI | ✅ Compatible | npx faf-taf-git --commit | | Azure Pipelines | ✅ Compatible | npx faf-taf-git --commit | | Local development | ✅ Works | npm test && npx faf-taf-git | | Pre-commit hooks | ✅ Works | See Examples |

Architecture: Platform-agnostic core. No CI-specific dependencies. Pure functions.

⏰ WHEN

Use faf-taf-git when you need:

1. Proof of testing over time

   • Regulated industries (SOC 2, ISO, HIPAA)
   • Open source credibility (show your tests pass)
   • Client deliverables (prove quality)

2. AI-augmented development

   • Give AI your test history (feeds .faf format)
   • AI can see: "Tests were 85% passing, now 99%"
   • Better context = better AI assistance

3. Debugging flaky tests

   • Timeline shows when tests started failing
   • Pattern detection (fails on Windows only, etc.)
   • Root cause analysis with historical data

4. Team accountability

   • PRs show test impact (IMPROVED, DEGRADED, etc.)
   • No hiding broken tests
   • Git history = test history

Don't use when:

• You only need current test status (use a test reporter)
• You don't commit to git (TAF is git-native)
• You're not ready for accountability 😉

🚀 HOW

Quick Start (GitHub Actions)

Step 1: Create .taf file

npm install -g faf-cli
faf taf init

Step 2: Add to CI workflow

name: Tests

on:
  push:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    permissions:
      contents: write  # Required for auto-commit

    steps:
      - uses: actions/checkout@v6

      - name: Setup Node.js
        uses: actions/setup-node@v6
        with:
          node-version: '20.x'

      - name: Install dependencies
        run: npm ci

      - name: Build
        run: npm run build

      - name: Run Tests and Capture Output
        run: npm test 2>&1 | tee test-output.txt

      - name: Generate TAF Receipt
        uses: Wolfe-Jam/[email protected]
        with:
          test-output-file: test-output.txt
          auto-commit: 'true'
          commit-message: 'chore(taf): update .taf receipt [skip ci]'

Step 3: Push and watch

• Tests run automatically
• .taf file updates with new entry
• Changes committed back to repo
• History tracked in git

Standalone CLI (Any Platform)

# Run tests and update .taf
npm test 2>&1 | tee test-output.txt
npx faf-taf-git --file test-output.txt --commit

# Or in one command (legacy v1.x CLI)
npx faf-taf-git --command "npm test" --commit

GitLab CI

test:
  script:
    - npm ci
    - npm test 2>&1 | tee test-output.txt
    - npx faf-taf-git --file test-output.txt --commit --message "ci: update .taf [skip ci]"

Jenkins

stage('Test') {
  steps {
    sh 'npm ci'
    sh 'npm test 2>&1 | tee test-output.txt'
    sh 'npx faf-taf-git --file test-output.txt --commit'
  }
}

Local Development

# Run tests and update .taf (no commit)
npm test 2>&1 | tee test-output.txt
npx faf-taf-git --file test-output.txt --verbose

# Pre-commit hook
#!/bin/bash
npm test 2>&1 | tee test-output.txt && npx faf-taf-git --file test-output.txt

🎨 HOW IT WORKS

v2.0.0+ Architecture (Pre-Capture Pattern)

Step 1: Run Tests              Step 2: Generate Receipt
┌─────────────────────┐        ┌──────────────────────┐
│ npm test 2>&1 |     │        │ faf-taf-git reads    │
│ tee test-output.txt │───────▶│ test-output.txt and  │
│                     │        │ updates .taf file    │
└─────────────────────┘        └──────────────────────┘

Why separate steps?

• Avoids GitHub Actions execution context corruption
• More reliable (tested 19 methods before this breakthrough)
• Platform-agnostic (works in ANY CI/CD)
• Simpler architecture (400+ lines removed)

Process:

1. Capture output - npm test 2>&1 | tee test-output.txt
2. Parse results - Extracts test counts from Jest output
3. Update .taf - Appends new test run to timeline
4. Commit - Optionally commits changes to git

📋 API

GitHub Action Inputs

| Input | Description | Default | Required | |-------|-------------|---------|----------| | test-output-file | Path to file containing test output | - | ✅ Yes | | auto-commit | Automatically commit .taf updates | true | No | | commit-message | Custom commit message | chore(taf): update .taf receipt [skip ci] | No |

GitHub Action Outputs

| Output | Description | Example | |--------|-------------|---------| | result | Test result | PASSED, FAILED, IMPROVED, DEGRADED | | passed | Number of tests passed | 799 | | failed | Number of tests failed | 0 | | total | Total number of tests | 808 | | skipped | Number of skipped tests | 9 | | taf-updated | Whether .taf was updated | true or false |

CLI Options

npx faf-taf-git [options]

Options:
  --file <path>       Path to test output file (v2.0.0+)
  --command <cmd>     Test command to run (legacy v1.x)
  --commit            Auto-commit .taf changes
  --message <msg>     Custom commit message
  --cwd <dir>         Working directory
  --verbose, -v       Verbose output
  --help, -h          Show help

🧪 Test Framework Support

| Framework | Status | Notes | |-----------|--------|-------| | Jest | ✅ Fully supported | All output formats | | Mocha | ⏳ Planned | - | | Vitest | ⏳ Planned | - | | Pytest | ⏳ Planned | - | | Go test | ⏳ Planned | - | | Rust cargo test | ⏳ Planned | - |

🎓 Examples

Using Outputs

- name: Generate TAF Receipt
  id: taf
  uses: Wolfe-Jam/[email protected]
  with:
    test-output-file: test-output.txt

- name: Check Results
  run: |
    echo "Result: ${{ steps.taf.outputs.result }}"
    echo "Tests: ${{ steps.taf.outputs.passed }}/${{ steps.taf.outputs.total }} passing"
    if [ "${{ steps.taf.outputs.result }}" == "DEGRADED" ]; then
      echo "⚠️ Test quality degraded!"
      exit 1
    fi

CircleCI

version: 2.1

jobs:
  test:
    docker:
      - image: node:20
    steps:
      - checkout
      - run: npm ci
      - run: npm test 2>&1 | tee test-output.txt
      - run: npx faf-taf-git --file test-output.txt --commit

Pre-commit Hook

#!/bin/bash
# .git/hooks/pre-commit

# Run tests and capture output
npm test 2>&1 | tee test-output.txt
TEST_EXIT=$?

# Update .taf (don't commit yet - that's what the commit is for!)
npx faf-taf-git --file test-output.txt

# Exit with test status
exit $TEST_EXIT

🏆 The Golden Triangle

Projects with .faf + repo + .taf are engineered to succeed:

       .faf
     (WHAT IT IS)
         /    \
        /      \
       /        \
    repo    ←→   .taf
(IMPLEMENTATION) (PROOF IT WORKS)

• .faf - Tells AI what the repo is (better than prose)
• repo - The implementation (code doesn't lie)
• .taf - Proves it works (receipts don't negotiate)

Why this matters:

• AI reads .faf to understand your project
• AI reads .taf to understand test quality
• Better context = better AI assistance
• Accountability built in

🔧 Development

Build

npm run build

Test

npm test

Package (GitHub Action)

npm run package  # Creates bundled dist/index.js

Test Locally

npm run build
node dist/cli.js --help

📖 Migration from v1.x

v2.0.0 is a breaking change - the architecture was redesigned for reliability.

What Changed

v1.x (test-command):

- uses: Wolfe-Jam/faf-taf-git@v1
  with:
    test-command: npm test

v2.x (test-output-file):

- run: npm test 2>&1 | tee test-output.txt

- uses: Wolfe-Jam/[email protected]
  with:
    test-output-file: test-output.txt

Why the Change

v1.x ran tests inside the action using @actions/exec. This caused:

• GitHub Actions execution context corruption
• Logging failures (tested 19 different methods)
• Filesystem operations failing silently
• Unreliable receipt generation

v2.0.0 uses pre-capture pattern - separate test execution from receipt generation. This is:

• ✅ More reliable (no execution context issues)
• ✅ Platform-agnostic (works everywhere)
• ✅ Simpler (400+ lines removed, 11KB smaller)
• ✅ Production-ready (tested thoroughly)

Migration Steps

1. Update workflow to use test-output-file instead of test-command
2. Add test output capture step: npm test 2>&1 | tee test-output.txt
3. Update version to @v2.0.4

See CHANGELOG.md for complete version history.

🤝 Contributing

See CONTRIBUTING.md for development guidelines.

📚 Learn More

• FAF CLI - Create and manage .faf files
• MCP Server - Claude MCP integration
• Website - Official FAF website
• GitHub Discussions - Ask questions

📄 License

MIT - FREE FOREVER

💎 Philosophy

Software Accountability

This tool implements a paradigm shift:

Before: Tests run → results disappear → no permanent record

After: Tests run → .taf updated → git-tracked forever

.taf is about accountability. Proof that your code works. Tracked over time. Visible to everyone.

Built with championship standards. F1-inspired engineering. Methodically tested.

Platform-agnostic core. Works everywhere. Trust the format.