Flow Test Logo

7.reporting / Guide

Flow Test Dashboard

Reporting Guide

Flow Test Engine generates a comprehensive JSON report after each execution. This file serves as the source of truth for integrations, dashboards, and CI/CD pipelines. HTML visualization is now handled exclusively through the built-in dashboard system.

JSON Results

The results/latest.json file contains all execution details, including metrics, suites, steps, and final variables.

{
  "project_name": "My API Tests",
  "start_time": "2025-09-21T10:51:16.787Z",
  "end_time": "2025-09-21T10:51:18.841Z",
  "total_duration_ms": 2054,
  "total_tests": 32,
  "successful_tests": 32,
  "failed_tests": 0,
  "success_rate": 100,
  "suites_results": [
    {
      "node_id": "auth-tests",
      "suite_name": "Authentication Tests",
      "status": "success",
      "duration_ms": 1250,
      "steps_results": [
        {
          "step_name": "Login with valid credentials",
          "status": "success",
          "duration_ms": 420
        }
      ]
    }
  ],
  "report_metadata": {
    "generated_at": "2025-09-21T10:51:18.841Z",
    "format": "json",
    "version": "1.1.1"
  }
}

Dashboard (HTML Viewer)

The dashboard is built with Astro and Tailwind CSS. It reads results/latest.json and provides a complete web interface with filters, charts, and step inspection.

Dashboard Commands

# Install dashboard dependencies (first time only)
fest dashboard install

# Start development server with hot reload
fest dashboard dev

# Build static dashboard for deployment
fest dashboard build

# Preview the built dashboard
fest dashboard preview

# Build and serve dashboard (production mode)
fest dashboard serve

Dashboard Data Location

The dashboard automatically searches for report data in the following order:

  1. Project results directory: When run via CLI, automatically detects your project location
  2. Configuration-based path: Based on output_dir in your flow-test.config.yml
  3. Relative path: ../results/latest.json (legacy fallback)
  4. Local data directory: src/data/latest.json (for manual copying)

Global Installation Support

Starting from version 1.1.1, the dashboard automatically resolves data location issues when using global installations:

# This now works correctly from any project directory
cd /path/to/your/project
flow-test dashboard dev

The CLI passes the current project directory to the dashboard, ensuring it can locate your results regardless of where Flow Test Engine is installed.

✅ Automatic Resolution: No manual file copying needed when using flow-test dashboard commands!

Example Usage

# Navigate to your project
cd ~/my-api-project

# Run tests to generate results
fest

# Start dashboard (automatically finds results)
fest dashboard dev
# → Opens http://localhost:4321/flow-test with your actual test results

# Or build static dashboard for deployment
fest dashboard build
# → Generates static files in report-dashboard/dist

The dashboard will be available at http://localhost:4321/flow-test or the next available port when running in development mode.

Configuration in flow-test.config.yml

reporting:
  formats: ["json"]              # Only format supported by the engine
  output_dir: "./results"        # Where latest.json will be saved
  aggregate: true                # Maintains global aggregations
  include_performance_metrics: true
  include_variables_state: true

ℹ️ The engine only supports JSON format. Other formats in the configuration will be ignored.

Usage in CI/CD

The minimal requirement is to persist results/latest.json as an artifact. If you want to publish the static dashboard, run the build after the tests.

GitHub Actions

name: API Tests
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '18'

      - name: Install dependencies
        run: npm ci

      - name: Run Flow Tests
        run: flow-test --priority critical,high

      - name: Upload test results
        uses: actions/upload-artifact@v4
        if: always()
        with:
          name: test-results
          path: results/latest.json

      - name: Build dashboard
        if: always()
        run: |
          flow-test dashboard install
          flow-test dashboard build

      - name: Deploy dashboard to GitHub Pages
        if: github.ref == 'refs/heads/main'
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./report-dashboard/dist
steps:
  - uses: actions/checkout@v3
  - uses: actions/setup-node@v4
    with:
      node-version: '18'

  - name: Install dependencies
    run: npm install

  - name: Run tests
    run: npm test

  - name: Build dashboard (optional)
    run: npm run report:dashboard:build

  - name: Upload artifacts
    uses: actions/upload-artifact@v4
    with:
      name: flow-test-results
      path: |
        results/latest.json
        report-dashboard/dist

### Jenkins Pipeline

```groovy
pipeline {
  agent any

  stages {
    stage('Install') {
      steps {
        sh 'npm install'
      }
    }

    stage('Test') {
      steps {
        sh 'npm test'
      }
    }

    stage('Build Dashboard') {
      steps {
        sh 'npm run report:dashboard:build'
      }
    }
  }

  post {
    always {
      archiveArtifacts artifacts: 'results/latest.json'
      archiveArtifacts artifacts: 'report-dashboard/dist/**', fingerprint: true
    }
  }
}

Troubleshooting

Dashboard Shows Mock Data

If the dashboard displays “Mock Data” instead of your real test results:

  1. Verify results exist: Check that results/latest.json exists in your project
  2. Check working directory: Ensure you run flow-test dashboard dev from your project root
  3. Verify configuration: Check that output_dir in flow-test.config.yml matches your results location

Manual Data Copy (Legacy)

For older versions or special setups, you can manually copy results:

# Find your global installation path
npm list -g flow-test-engine

# Copy results manually
mkdir -p /path/to/global/flow-test-engine/report-dashboard/src/data
cp ./results/latest.json /path/to/global/flow-test-engine/report-dashboard/src/data/

Custom Results Location

If your results are in a non-standard location, update your configuration:

# flow-test.config.yml
reporting:
  output_dir: "./custom-results-dir"

The dashboard will automatically detect and use this custom location.


## Customização do Dashboard

Todo o código visual mora em `report-dashboard/src/`. Lá você pode alterar componentes, temas e integrações com analytics. O engine principal se limita a persistir o JSON.

- Ajuste estilos em `report-dashboard/src/styles/`.
- Adicione widgets novos em `report-dashboard/src/components/`.
- Atualize `report-dashboard/astro.config.mjs` para mudar base path ou integrações.

## Checklist Rápido

- [x] Rode os testes (`npm test`) → garante `results/latest.json` atualizado.
- [x] Opcional: `npm run report:dashboard:build` para gerar versão estática.
- [x] Publique os artefatos desejados (JSON e/ou build estático).
- [x] Compartilhe o link do dashboard ou anexe o JSON no MR/PR.
Flow Test Engine
© 2025 Flow Test Engine. Dynamic Reporting System.