faf-taf-git

The Git-Native Receipt Printer - test results that never disappear.

npm: faf-taf-git · action: Wolfe-Jam/faf-taf-git

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:

Proof of testing over time
- Regulated industries (SOC 2, ISO, HIPAA)
- Open source credibility (show your tests pass)
- Client deliverables (prove quality)
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
Debugging flaky tests
- Timeline shows when tests started failing
- Pattern detection (fails on Windows only, etc.)
- Root cause analysis with historical data
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/faf-taf-git@v2.0.4
        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:

Capture output - npm test 2>&1 | tee test-output.txt
Parse results - Extracts test counts from Jest output
Update .taf - Appends new test run to timeline
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
Vitest	✅ Fully supported	Including todo counts
Mocha	⏳ Planned	-
Pytest	⏳ Planned	-
Go test	⏳ Planned	-
Rust cargo test	⏳ Planned	-

🎓 Examples

Using Outputs

- name: Generate TAF Receipt
  id: taf
  uses: Wolfe-Jam/faf-taf-git@v2.0.4
  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/faf-taf-git@v2.0.4
  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

Update workflow to use test-output-file instead of test-command
Add test output capture step: npm test 2>&1 | tee test-output.txt
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.

Name		Name	Last commit message	Last commit date
Latest commit History 78 Commits
.github/workflows		.github/workflows
dist		dist
docs		docs
src		src
tests		tests
.faf-dna		.faf-dna
.fafignore		.fafignore
.gitignore		.gitignore
.taf		.taf
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
action.yml		action.yml
badge.svg		badge.svg
jest.config.js		jest.config.js
package-lock.json		package-lock.json
package.json		package.json
project.faf		project.faf
test-mcp.ts		test-mcp.ts
test-standalone.ts		test-standalone.ts
tsconfig.json		tsconfig.json

License

Wolfe-Jam/faf-taf-git

Folders and files

Latest commit

History

Repository files navigation

faf-taf-git

🎯 WHAT

👥 WHO

🤔 WHY

The Problem

The Solution

📍 WHERE

⏰ WHEN

🚀 HOW

Quick Start (GitHub Actions)

Standalone CLI (Any Platform)

GitLab CI

Jenkins

Local Development

🎨 HOW IT WORKS

v2.0.0+ Architecture (Pre-Capture Pattern)

📋 API

GitHub Action Inputs

GitHub Action Outputs

CLI Options

🧪 Test Framework Support

🎓 Examples

Using Outputs

CircleCI

Pre-commit Hook

🏆 The Golden Triangle

🔧 Development

Build

Test

Package (GitHub Action)

Test Locally

📖 Migration from v1.x

What Changed

Why the Change

Migration Steps

🤝 Contributing

📚 Learn More

📄 License

💎 Philosophy

About

Topics

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 5

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages