Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/gha-common/go-beautiful-html-coverage

A GitHub Action to track code coverage in your pull requests, with a beautiful HTML preview, for free.
https://github.com/gha-common/go-beautiful-html-coverage

coverage coverage-report go golang

Last synced: 3 months ago
JSON representation

A GitHub Action to track code coverage in your pull requests, with a beautiful HTML preview, for free.

Awesome Lists containing this project

README

        

# `go-beautiful-html-coverage`
[![Mentioned in Awesome Go](https://awesome.re/mentioned-badge-flat.svg)](https://github.com/avelino/awesome-go)

A GitHub Action to track code coverage in your pull requests, with [a beautiful HTML preview ↗](https://kilianc.github.io/pretender/head/head.html#file0), for free.

Buy Me A Coffee

## Usage

To use this action simply add it to your pre-existent ci workflow. A bare minimal example might look like this:

```yaml
name: Go

on:
push:
branches: [ "main" ]
pull_request:
branches: [ "main" ]

jobs:
test:
name: Build and Test
runs-on: ubuntu-latest
permissions:
pull-requests: write # required for posting comments
contents: write # required for git push
steps:
- uses: actions/checkout@v4

- name: Set up Go
uses: actions/setup-go@v5

- name: Test # this should generate cover.out
run: make test

- name: Go Beautiful HTML Coverage
uses: 'gha-common/go-beautiful-html-coverage@v1'
```

## How it works

This GHA expects `cover.out` to be present in the root of your repo at runtime. `cover.out` is usually generated by `go test` when passing the `-coverprofile=cover.out` flag:

```sh
go test -coverprofile=cover.out ./...
```

For examples on how you might do that you can peak at [`go-test-app/Makefile`](./Makefile), or some of my other go projects like [`pretender`](https://github.com/kilianc/pretender/blob/main/Makefile#L44-L57) and [`base-go-cli`](https://github.com/kilianc/base-golang-cli/blob/main/Makefile#L76-L92).

Once your test has ran and `cover.out` has been generated, the GHA does the following:

1. Create and push [new orphan branch](https://github.com/gha-common/go-beautiful-html-coverage/tree/cover) if one doesn't exist.
1. Generate `cover.html` and `cover.txt` from `cover.out`.
1. Customize `cover.html` and rename it `.html`.
1. `git-push` the `.html` file to the orphan branch. This will trigger a `GitHub Pages` deployment.
1. Post a comment to your PR with your code coverage summary (`cover.txt`) and a link to your `.html`.

### Screenshots



PR Comment
HTML Preview (Dark)
HTML Preview (Light)


> [!NOTE]
> In order for the HTML preview links to work, configure `GitHub Pages` in your target repo *(`Settings > Pages`)* to `Deploy from a branch` and pick your target branch, which is, by default, `cover`.
>
> ![GitHub Pages Setup](https://github.com/gha-common/go-beautiful-html-coverage/assets/385716/a14f4df6-6263-4ae3-8685-e7901a1dbbe2)

## Reference

```yaml
- name: Go Beautiful HTML Coverage
uses: 'gha-common/go-beautiful-html-coverage@v1'
with:
# Repository name with owner. For example, actions/checkout.
# Default: ${{ github.repository }}
repository: ''

# The branch to checkout or create and push coverage to.
# Default: 'cover'
branch: ''

# The token to use for pushing to the repository.
# Default: ${{ github.token }}
token: ''

# The relative path of your go project. Useful for monorepos and custom folder structures.
# Default: ./
path: ''

# The minimum % of coverage required.
# Default: 0
threshold: ''
```

## Examples

**You can customize the name of the branch that hosts the code coverage files.**

```yaml
- name: Go Beautiful HTML Coverage
uses: 'gha-common/go-beautiful-html-coverage@v1'
with:
branch: 'my-coverage'
```

Just make sure to update the `GitHub Pages` deployment settings to match.

**You can customize the repository that hosts the code coverage files.**

This is helpful if you don't want to clutter your project's repo, or if you want to centralize coverage reporting across multiple repos, or you can't turn on `GitHub Pages` in your project's repo.

```yaml
- name: Go Beautiful HTML Coverage
uses: 'gha-common/go-beautiful-html-coverage@v1'
with:
repository: yourname/coverage
token: ${{ secrets.GHA_COVERAGE_TOKEN }}
```

Where `GHA_COVERAGE_TOKEN` is a repository secret with a personal token that has write access to `yourname/coverage`.

**You can customize the path to your go project in the repo.**

This is helpful if you have a monorepo with multiple apps, or simply you keep your go files in a subfolder. Just make sure to generate `cover.out` for all your apps before running this GHA.

```yaml
- name: Go Beautiful HTML Coverage
uses: 'gha-common/go-beautiful-html-coverage@v1'
with:
path: ./go-app-01

- name: Go Beautiful HTML Coverage
uses: 'gha-common/go-beautiful-html-coverage@v1'
with:
path: ./go-app-02
```

## License

MIT License, see [LICENSE](./LICENSE.md)