Skip to content

Commit

Permalink
chore: update examples (#19)
Browse files Browse the repository at this point in the history
  • Loading branch information
kilianc authored May 12, 2024
1 parent 4d4db59 commit 272c57a
Showing 1 changed file with 26 additions and 26 deletions.
52 changes: 26 additions & 26 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,28 +3,6 @@

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

## How it works

This GHA expects two files to be present in the root of your repo at runtime:

- `cover.txt` is the output of `go tool cover -func=cover.out -o cover.txt`
- `cover.html` is the output of `go tool cover -html=cover.out -o cover.html`

Both `go tool cover` commands can be configured to your liking. For examples on how you might do that you can peak at [`Makefile`](go-test-app/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 the files are generated, the GHA does the following:

1. Create and push [new orphan branch](https://github.com/kilianc/go-beautiful-html-coverage/tree/cover) if one doesn't exist.
1. Customize `cover.html` with [`nord.css`](assets/nord.css) 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

<br>
<img width="912" alt="PR Comment" src="https://github.com/kilianc/go-beautiful-html-coverage/assets/385716/99b01c85-f573-44cb-b554-64e9495aa7d1">
<img width="822" alt="HTML Preview" src="https://github.com/kilianc/go-beautiful-html-coverage/assets/385716/bb4361f3-34db-4c9d-9970-794d3dded7b9">

## Usage

To use this action simply add it to your pre-existent ci workflow. A bare minimal example might look like this:
Expand Down Expand Up @@ -54,10 +32,32 @@ jobs:
- name: Test # this should generate cover.<txt|html>
run: make test

- name: Go Coverage
- name: Go Beautiful HTML Coverage
uses: 'kilianc/go-beautiful-html-coverage@main'
```
## How it works
This GHA expects two files to be present in the root of your repo at runtime:
- `cover.txt` is the output of `go tool cover -func=cover.out -o cover.txt`
- `cover.html` is the output of `go tool cover -html=cover.out -o cover.html`

Both `go tool cover` commands can be configured to your liking. For examples on how you might do that you can peak at [`Makefile`](go-test-app/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 the files are generated, the GHA does the following:

1. Create and push [new orphan branch](https://github.com/kilianc/go-beautiful-html-coverage/tree/cover) if one doesn't exist.
1. Customize `cover.html` with [`nord.css`](assets/nord.css) 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

<br>
<img width="912" alt="PR Comment" src="https://github.com/kilianc/go-beautiful-html-coverage/assets/385716/99b01c85-f573-44cb-b554-64e9495aa7d1">
<img width="822" alt="HTML Preview" src="https://github.com/kilianc/go-beautiful-html-coverage/assets/385716/bb4361f3-34db-4c9d-9970-794d3dded7b9">

> [!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`.
>
Expand All @@ -66,7 +66,7 @@ jobs:
## Reference

```yaml
- name: Go Coverage
- name: Go Beautiful HTML Coverage
uses: 'kilianc/go-beautiful-html-coverage@main'
with:
# Repository name with owner. For example, actions/checkout.
Expand All @@ -87,7 +87,7 @@ jobs:
**You can customize the name of the branch that hosts the code coverage files.**

```yaml
- name: Go Coverage
- name: Go Beautiful HTML Coverage
uses: 'kilianc/go-beautiful-html-coverage@main'
with:
branch: 'my-coverage'
Expand All @@ -100,7 +100,7 @@ Just make sure to update the `GitHub Pages` deployment settings to match.
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 Coverage
- name: Go Beautiful HTML Coverage
uses: 'kilianc/go-beautiful-html-coverage@main'
with:
repository: yourname/coverage
Expand Down

0 comments on commit 272c57a

Please sign in to comment.