Blossom Compliance Test Suite

Automated test suite for validating Blossom server implementations against the BUD specifications.

Quick Start

# Test a single server
npx blossom-compliance https://your-server.com

# Or with bun directly
bun run cli.ts https://your-server.com

# Test multiple servers
npx blossom-compliance https://host1.com https://host2.com

This runs all BUD test modules and writes an HTML report to report/index.html and raw JSON to report/results.json.

Running from Source

# Install bun if you don't have it
curl -fsSL https://bun.sh/install | bash

# Install dependencies
bun install

# Test a single server
BLOSSOM_SERVER_URL=https://your-server.com bun run report.ts

# Or use the CLI
bun run cli.ts https://your-server.com

Using in GitHub CI

With npx

name: Blossom Compliance

on: [push, pull_request]

jobs:
  compliance:
    runs-on: ubuntu-latest
    steps:
      # Start your Blossom server (adjust to your setup)
      - run: |
          your-server-start-command &
          sleep 5

      - uses: oven-sh/setup-bun@v2

      - name: Run compliance tests
        run: npx blossom-compliance http://localhost:3000

      - name: Upload compliance report
        uses: actions/upload-artifact@v4
        if: always()
        with:
          name: compliance-report
          path: report/

From Source

name: Blossom Compliance

on: [push, pull_request]

jobs:
  compliance:
    runs-on: ubuntu-latest
    steps:
      - run: |
          your-server-start-command &
          sleep 5

      - uses: actions/checkout@v4
        with:
          repository: hzrd149/blossom
          path: compliance-test-repo
          sparse-checkout: compliance-test

      - uses: oven-sh/setup-bun@v2

      - run: bun install
        working-directory: compliance-test-repo/compliance-test

      - name: Run compliance tests
        working-directory: compliance-test-repo/compliance-test
        env:
          BLOSSOM_SERVER_URL: http://localhost:3000
        run: bun run report.ts

      - name: Upload compliance report
        uses: actions/upload-artifact@v4
        if: always()
        with:
          name: compliance-report
          path: compliance-test-repo/compliance-test/report/

Failing the Build on Test Failures

The report command always exits 0 and produces a report. To fail the CI job when mandatory BUD tests fail, parse the JSON report:

      - name: Check for failures
        run: |
          FAILS=$(jq '[.[].buds[].cases[] | select(.status == "fail")] | length' report/results.json)
          if [ "$FAILS" -gt 0 ]; then
            echo "::error::$FAILS mandatory compliance test(s) failed"
            exit 1
          fi

Test Coverage

| BUD | Mandatory | Description | |-----|-----------|-------------| | BUD-00 | Yes | Server Reachability | | BUD-01 | Yes | Blossom Server Basics (CORS, error responses, blob retrieval, HEAD, range requests) | | BUD-02 | No | Blob Upload (PUT /upload, descriptors, X-SHA-256, duplicate handling) | | BUD-04 | No | Blob Mirror (PUT /mirror) | | BUD-05 | No | Media Optimization (PUT /media, HEAD /media) | | BUD-06 | No | Upload Requirements (HEAD /upload pre-flight) | | BUD-07 | No | Paid Upload and Download (402, X-Cashu, X-Lightning) | | BUD-08 | No | Nostr File Metadata Tags (nip94 field in descriptors) | | BUD-09 | No | Blob Report (PUT /report with kind:1984 events) | | BUD-11 | No | Nostr Authorization (kind:24242 tokens, t/x/server tag validation) | | BUD-12 | No | Blob Management (GET /list/<pubkey>, DELETE /<sha256>) |

Optional BUD failures are reported as warnings rather than failures.