go-beautiful-html-coverage

KO | EN

gitlite — search

#javascript #python #hacktoberfest #react #ai #typescript #llm #go #golang #android #machine-learning #rust #deep-learning #linux

go-beautiful-html-coverage

★ 24 Open GitHub ↗

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

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# `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.

## 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 `<sha>.html`.
1. `git-push` the `<sha>.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 `<sha>.html`.

### Screenshots

> [!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)

go-beautiful-html-coverage

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README