From b5e5cb6a5342e5094ff30f7bbe098daa7edfdd59 Mon Sep 17 00:00:00 2001 From: Matthew Thomas Date: Sat, 11 Jan 2025 20:27:46 +0000 Subject: [PATCH 1/6] feat: community reports --- .github/workflows/community.yaml | 32 ++++++++++++ .prettierignore | 1 + README.md | 50 ++++++++++++++++++- community-reports/summary-short/README.md | 26 ++++++++++ .../summary-short/summary-short.hbs | 3 ++ package-lock.json | 4 +- package.json | 6 +-- src/config/index.ts | 1 + src/core/cli.ts | 16 ++++++ src/core/inputs.ts | 4 ++ src/github/core.ts | 16 +++++- src/types/reporter.ts | 2 + 12 files changed, 153 insertions(+), 8 deletions(-) create mode 100644 .github/workflows/community.yaml create mode 100644 community-reports/summary-short/README.md create mode 100644 community-reports/summary-short/summary-short.hbs diff --git a/.github/workflows/community.yaml b/.github/workflows/community.yaml new file mode 100644 index 00000000..3044b63e --- /dev/null +++ b/.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 example --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 \ No newline at end of file diff --git a/.prettierignore b/.prettierignore index 3cc66b04..2da2bc23 100644 --- a/.prettierignore +++ b/.prettierignore @@ -3,5 +3,6 @@ node_modules/ coverage/ templates/ reports/ +community-reports/ .github/ .exlintrc.js diff --git a/README.md b/README.md index 0858f0c4..1e57c96d 100644 --- a/README.md +++ b/README.md @@ -271,6 +271,18 @@ 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() +``` + ### Post a Pull Request Comment To post a comment on the pull request with test results, add the `pull-request` @@ -401,7 +413,7 @@ 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 +- Runs from the same branch for events of type push and schedule from the same workflow id - Runs from the same pull request for events of type pull_request from the same workflow id @@ -496,6 +508,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 +544,37 @@ 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 a Community Report + +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 diff --git a/community-reports/summary-short/README.md b/community-reports/summary-short/README.md new file mode 100644 index 00000000..13c29322 --- /dev/null +++ b/community-reports/summary-short/README.md @@ -0,0 +1,26 @@ +# 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 diff --git a/community-reports/summary-short/summary-short.hbs b/community-reports/summary-short/summary-short.hbs new file mode 100644 index 00000000..eec4a0cc --- /dev/null +++ b/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}} | \ No newline at end of file diff --git a/package-lock.json b/package-lock.json index f410d318..b74efa19 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "github-actions-ctrf", - "version": "0.0.55", + "version": "0.0.56", "lockfileVersion": 2, "requires": true, "packages": { "": { "name": "github-actions-ctrf", - "version": "0.0.55", + "version": "0.0.56", "license": "MIT", "dependencies": { "@actions/core": "^1.11.1", diff --git a/package.json b/package.json index 741175eb..1047faa9 100644 --- a/package.json +++ b/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" @@ -89,4 +89,4 @@ "handlebars": "^4.7.8", "yargs": "^17.7.2" } -} +} \ No newline at end of file diff --git a/src/config/index.ts b/src/config/index.ts index 64a646ca..2af5e38a 100644 --- a/src/config/index.ts +++ b/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' diff --git a/src/core/cli.ts b/src/core/cli.ts index 7671d6d1..a89c4f46 100644 --- a/src/core/cli.ts +++ b/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 { }) } ) + .command( + 'community ', + '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 ', 'Generate historical test results table from a CTRF report', diff --git a/src/core/inputs.ts b/src/core/inputs.ts index b1378b72..eb419efa 100644 --- a/src/core/inputs.ts +++ b/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') || '', diff --git a/src/github/core.ts b/src/github/core.ts index 2dc8c749..b408cd6e 100644 --- a/src/github/core.ts +++ b/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) } diff --git a/src/types/reporter.ts b/src/types/reporter.ts index 81e74fc6..b7efce2c 100644 --- a/src/types/reporter.ts +++ b/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 From 859601935034e2fb81e9a87d8d5f84b84dc8c5c2 Mon Sep 17 00:00:00 2001 From: Matthew Thomas Date: Sat, 11 Jan 2025 20:30:03 +0000 Subject: [PATCH 2/6] chore: format --- .github/workflows/community.yaml | 2 +- README.md | 33 +++++++++++++++++++++----------- package.json | 2 +- 3 files changed, 24 insertions(+), 13 deletions(-) diff --git a/.github/workflows/community.yaml b/.github/workflows/community.yaml index 3044b63e..25b06ad5 100644 --- a/.github/workflows/community.yaml +++ b/.github/workflows/community.yaml @@ -19,7 +19,7 @@ jobs: - name: Build run: npm run build - name: Test community report - run: node dist/core/cli.js community ctrf-reports/ctrf-report.json example --title "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: diff --git a/README.md b/README.md index 1e57c96d..f8240dff 100644 --- a/README.md +++ b/README.md @@ -273,13 +273,14 @@ your workflow: ### 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: +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 + npx github-actions-ctrf community path-to-your-ctrf-report.json + report-template-name if: always() ``` @@ -548,7 +549,9 @@ For inspiration on what you can create, check out the ### 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. +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 a Community Report @@ -556,25 +559,33 @@ We welcome and encourage contributions of community-built reports. Community rep 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`). + 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: + + - **`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. + 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. +- **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 diff --git a/package.json b/package.json index 1047faa9..1abcbde8 100644 --- a/package.json +++ b/package.json @@ -89,4 +89,4 @@ "handlebars": "^4.7.8", "yargs": "^17.7.2" } -} \ No newline at end of file +} From a20a7de811bbab61178cea481bd0b2c1f8102ce6 Mon Sep 17 00:00:00 2001 From: Matthew Thomas Date: Sat, 11 Jan 2025 20:33:18 +0000 Subject: [PATCH 3/6] docs: add example --- community-reports/summary-short/README.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/community-reports/summary-short/README.md b/community-reports/summary-short/README.md index 13c29322..319d2555 100644 --- a/community-reports/summary-short/README.md +++ b/community-reports/summary-short/README.md @@ -24,3 +24,7 @@ community-report-name: summary-short 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 | From abf1012d292b509414d65a40fddb9efc87b03c21 Mon Sep 17 00:00:00 2001 From: Matthew Thomas Date: Sat, 11 Jan 2025 20:40:36 +0000 Subject: [PATCH 4/6] docs: community reports --- README.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index f8240dff..fd5a35db 100644 --- a/README.md +++ b/README.md @@ -284,6 +284,8 @@ and the name of the report template: 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` @@ -553,7 +555,7 @@ 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 a Community Report +#### How To Contribute Your Own Reports 1. **Fork the Repository** Start by forking this repository to your GitHub account. From d21893c1d29c0980318c27677aea19f66106c602 Mon Sep 17 00:00:00 2001 From: Matthew Thomas Date: Sat, 11 Jan 2025 20:42:06 +0000 Subject: [PATCH 5/6] docs: fix format issues --- README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index fd5a35db..42e540c0 100644 --- a/README.md +++ b/README.md @@ -284,7 +284,8 @@ and the name of the report template: if: always() ``` -See the available [community reports](community-reports), or [add your own](#how-to-contribute-your-own-reports). +See the available [community reports](community-reports), or +[add your own](#how-to-contribute-your-own-reports). ### Post a Pull Request Comment From f93b00d5fa5d84b98e9ad5e51cba9a16133ea213 Mon Sep 17 00:00:00 2001 From: Matthew Thomas Date: Sat, 11 Jan 2025 20:51:54 +0000 Subject: [PATCH 6/6] docs: filter information --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 42e540c0..d92860c1 100644 --- a/README.md +++ b/README.md @@ -417,8 +417,8 @@ current workflow and job names: Filtering is applied as follows: -- Runs from the same branch for events of type push and schedule 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