Merge pull request #66 from ctrf-io/feat/community-reports

Feat/community reports

.github/workflows/community.yaml

@@ -0,0 +1,32 @@
+name: community-example
+
+on:
+  push:
+    branches:
+      - '**'
+  pull_request:
+    branches:
+      - '**'
+
+jobs:
+  testing:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+      - name: Install dependencies
+        run: npm install
+      - name: Build
+        run: npm run build
+      - name: Test community report
+        run: node dist/core/cli.js community ctrf-reports/ctrf-report.json summary-short --title "Community report"
+      - name: Upload test results
+        uses: actions/upload-artifact@v4
+        with:
+          name: ctrf-report
+          path: ctrf-reports/ctrf-report.json
+      - name: Upload test results
+        uses: actions/upload-artifact@v4
+        with:
+          name: custom-artifact-name
+          path: ctrf-reports/ctrf-report-no-fails.json

.prettierignore

@@ -3,5 +3,6 @@ node_modules/
 coverage/
 templates/
 reports/
+community-reports/
 .github/
 .exlintrc.js

README.md

@@ -271,6 +271,22 @@ your workflow:
   if: always()
 ```
 
+### Generating a Community Built Report
+
+To use a community built report, add the `community` command to your workflow
+and the name of the report template:
+
+```yaml
+- name: Publish CTRF Community Report
+  run:
+    npx github-actions-ctrf community path-to-your-ctrf-report.json
+    report-template-name
+  if: always()
+```
+
+See the available [community reports](community-reports), or
+[add your own](#how-to-contribute-your-own-reports).
+
 ### Post a Pull Request Comment
 
 To post a comment on the pull request with test results, add the `pull-request`
@@ -401,8 +417,8 @@ current workflow and job names:
 
 Filtering is applied as follows:
 
-- Runs from the same branch for events of type push, schedule and workflow_dispatch from the same
-  workflow id
+- Runs from the same branch for events of type push, schedule and
+  workflow_dispatch from the same workflow id
 - Runs from the same pull request for events of type pull_request from the same
   workflow id
 
@@ -496,6 +512,10 @@ When writing your template, you can use several special Handlebars helpers:
 
 - `{{eq arg1 arg2}}`: Compares two arguments and returns true if they are equal.
 
+See available helpers [here](src/handlebars/helpers).
+
+We welcome contributions for additional helpers.
+
 ### Available Properties
 
 All CTRF properties are accessible via the ctrf property in your template.
@@ -528,7 +548,47 @@ The following GitHub properties are available:
 ### Template Example
 
 For inspiration on what you can create, check out the
-[example template](templates/custom-summary.hbs)
+[built-in reports](src/reports) and [community reports](community-reports)
+
+### Community Reports
+
+We welcome and encourage contributions of community-built reports. Community
+reports allow users to share custom Handlebars templates designed for specific
+use cases or unique report styles.
+
+#### How To Contribute Your Own Reports
+
+1. **Fork the Repository**  
+   Start by forking this repository to your GitHub account.
+
+2. **Create a New Report Folder**  
+   Navigate to the `community-reports` directory and create a new folder named
+   after your report (e.g., `my-custom-report`).
+
+3. **Include the Following Files**  
+   Your report folder should include:
+
+   - **`my-custom-report.hbs`**: Your Handlebars template file. This is the core
+     of your report.
+   - **`README.md`**: Documentation about your report. Include the following
+     details:
+     - The purpose of your template.
+     - Instructions on how to use it.
+     - Any important considerations (e.g., required CTRF report properties).
+     - Example output
+
+4. **Submit a Pull Request**  
+   Once your report is ready, submit a pull request with a brief description of
+   your contribution. We will review it and provide feedback if necessary.
+
+#### Guidelines for Creating a Good Community Report
+
+- **Be Descriptive**: Ensure your `README.md` clearly explains the report's
+  purpose, usage, and any special requirements.
+- **Follow the Template Structure**: Maintain consistency with other community
+  reports in the repository.
+- **Keep It Useful**: Focus on templates that solve common problems or address
+  specific needs.
 
 ## Calculations
 

community-reports/summary-short/README.md

@@ -0,0 +1,30 @@
+# Template Name: summary-short
+
+## Description
+
+A brief description of what this template is for.  
+e.g., "This template provides a summary view with key metrics and links to
+failing test cases."
+
+---
+
+## How to Use
+
+Use this template by referencing its name:  
+`summary-short`
+
+Add this to your workflow file:
+
+```yaml
+community-report-name: summary-short
+```
+
+## Important Considerations
+
+Highlight important considerations e.g. particular CTRF report properties that should be included in the report
+
+## What it looks like
+
+| **Tests 📝** | **Passed ✅** | **Failed ❌** | **Duration ⏱️** |
+| --- | --- | --- | --- |
+| 10 | 5 | 3 | 11.0s |

community-reports/summary-short/summary-short.hbs

@@ -0,0 +1,3 @@
+| **Tests {{getCtrfEmoji "tests"}}** | **Passed {{getCtrfEmoji "passed"}}** | **Failed {{getCtrfEmoji "failed"}}** | **Duration {{getCtrfEmoji "duration"}}** |
+| --- | --- | --- | --- |
+| {{ctrf.summary.tests}} | {{ctrf.summary.passed}} | {{ctrf.summary.failed}} | {{formatDuration ctrf.summary.start ctrf.summary.stop}} |

package.json

@@ -1,6 +1,6 @@
 {
   "name": "github-actions-ctrf",
-  "version": "0.0.55",
+  "version": "0.0.56",
   "description": "View test results directly within your GitHub workflow summary and Pull Requests",
   "main": "index.js",
   "scripts": {
@@ -9,7 +9,7 @@
     "format:check": "npx prettier --check .",
     "lint": "npx eslint . -c ./.github/linters/.eslintrc.yml",
     "all": "npm run format:write && npm run lint && npm run test && npm run build",
-    "build": "tsc && copyfiles -u 2 \"src/reports/*.hbs\" dist/reports"
+    "build": "tsc && copyfiles -u 2 \"src/reports/*.hbs\" dist/reports && copyfiles -u 2 \"community-reports/**/*.hbs\" dist/community-reports"
   },
   "bin": {
     "github-actions-ctrf": "./dist/core/cli.js"

src/config/index.ts

@@ -1,2 +1,3 @@
 export const GITHUB_TOKEN = process.env.GITHUB_TOKEN
 export const GITHUB_API_URL = process.env.GITHUB_API_URL
+export const COMMUNITY_REPORTS_PATH = 'community-reports'

src/core/cli.ts

@@ -18,6 +18,7 @@ export interface Arguments {
   file?: string
   title?: string
   summary?: string
+  communityReportName?: string
   annotate?: boolean
   rows?: number
   artifactName?: string
@@ -206,6 +207,21 @@ async function main(): Promise<void> {
           })
       }
     )
+    .command(
+      'community <file> <community-report-name>',
+      'Generate a community built report from a CTRF report',
+      yargs => {
+        return yargs
+          .positional('file', {
+            describe: 'Path to the CTRF file',
+            type: 'string'
+          })
+          .positional('community-report-name', {
+            describe: 'Name of community report to use',
+            type: 'string'
+          })
+      }
+    )
     .command(
       'historical <file>',
       'Generate historical test results table from a CTRF report',

src/core/inputs.ts

@@ -26,6 +26,8 @@ export function getCliInputs(args: Arguments): Inputs {
     suiteListReport: args._.includes('suite-list'),
     pullRequestReport: args._.includes('pull-request'),
     customReport: args._.includes('custom'),
+    communityReport: args._.includes('community'),
+    communityReportName: args.communityReportName || '',
     artifactName: args.artifactName || 'ctrf-report',
     annotate: args.annotate !== false,
     title: args.title || '',
@@ -75,6 +77,8 @@ export function getInputs(): Inputs {
     pullRequestReport:
       core.getInput('pull-request-report').toLowerCase() === 'true',
     customReport: core.getInput('custom-report').toLowerCase() === 'true',
+    communityReport: core.getInput('community-report').toLowerCase() === 'true',
+    communityReportName: core.getInput('community-report-name'),
     artifactName: core.getInput('artifact-name') || 'ctrf-report',
     annotate: core.getInput('annotate').toLowerCase() === 'true',
     title: core.getInput('title') || '',

src/github/core.ts

@@ -4,6 +4,8 @@ import { generateMarkdown } from '../handlebars/core'
 import { Inputs, CtrfReport } from '../types'
 import { readTemplate } from '../utils'
 import { BuiltInReports } from '../reports/core'
+import { COMMUNITY_REPORTS_PATH } from '../config'
+import { join } from 'path'
 
 /**
  * Generates various views of the CTRF report and adds them to the GitHub Actions summary.
@@ -31,7 +33,8 @@ export function generateViews(inputs: Inputs, report: CtrfReport): void {
     inputs.suiteFoldedReport ||
     inputs.suiteListReport ||
     inputs.pullRequestReport ||
-    inputs.customReport
+    inputs.customReport ||
+    inputs.communityReport
 
   if (!isAnyReportEnabled) {
     core.info(
@@ -92,6 +95,17 @@ export function generateViews(inputs: Inputs, report: CtrfReport): void {
     core.summary.addRaw(customMarkdown).addEOL().addEOL()
   }
 
+  if (inputs.communityReport && inputs.communityReportName) {
+    const customTemplate = readTemplate(
+      join(
+        __dirname,
+        `../${COMMUNITY_REPORTS_PATH}/${inputs.communityReportName}.hbs`
+      )
+    )
+    const customMarkdown = generateMarkdown(customTemplate, report)
+    core.summary.addRaw(customMarkdown).addEOL().addEOL()
+  }
+
   if (inputs.testReport) {
     addViewToSummary('### Tests', BuiltInReports.TestTable, report)
   }

src/types/reporter.ts

@@ -18,6 +18,8 @@ export interface Inputs {
   suiteListReport: boolean
   pullRequestReport: boolean
   customReport: boolean
+  communityReport: boolean
+  communityReportName: string
   artifactName: string
   annotate: boolean
   title: string