octocov is a toolkit for collecting code metrics (code coverage, code to test ratio, test execution time and your own custom metrics).

Key features of octocov are:

• Useful both as a CI tool and as a CLI tool
• Support multiple coverage report formats.
• Support multiple code metrics.
• Support for even generating coverage report badges.
• Have a mechanism to aggregate reports from multiple repositories.

GitHub Actions for octocov is here !!

First, run test with coverage report output.

For example, in case of Go language, add -coverprofile=coverage.out option as follows

$ go test ./... -coverprofile=coverage.out

And generete .octocov.yml to your repository.

$ octocov init
.octocov.yml is generated

And set up a workflow file as follows and run octocov on GitHub Actions.

# .github/workflows/ci.yml
name: Test

on:
  pull_request:

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      -
        uses: actions/checkout@v3
      -
        uses: actions/setup-go@v4
        with:
          go-version-file: go.mod
      -
        name: Run tests with coverage report output
        run: go test ./... -coverprofile=coverage.out
      -
        uses: k1LoW/octocov-action@v1

Then, octocov comment the report of the code metrics to the pull request.

It is also possible to add reports to GitHub Actions Job Summaries by editing .octocov.yml.

It can also be inserted into the body of a pull request.

Note that only pull requests from the same repository can be commented on (Reporting to GitHub Actions Job Summaries is permitted). This is because the workflow token of a forked pull request does not have write permission.

octocov acts as a code metrics viewer on the terminal.

For example, in case of Go language, add -coverprofile=coverage.out option as follows

$ go test ./... -coverprofile=coverage.out

And run octocov ls-files , octocov view [FILE...] and octocov diff [REPORT_A] [REPORT_B]

By setting comment:, comment the reports to pull request.

# .octocov.yml
comment:
  hideFooterLink: false # hide octocov link

octocov checks for "Code Coverage" by default. If it is running on GitHub Actions, it will also measure "Test Execution Time".

If you want to measure "Code to Test Ratio", set codeToTestRatio:.

comment:
codeToTestRatio:
  code:
    - '**/*.go'
    - '!**/*_test.go'
  test:
    - '**/*_test.go'

By setting report: ( report.path: or report.datastores ) and diff: ( diff.path: or diff.datastores ) additionally, it is possible to show differences from previous reports as well.

comment:
report:
  datastores:
    - artifact://${GITHUB_REPOSITORY}
diff:
  datastores:
    - artifact://${GITHUB_REPOSITORY}

By setting coverage.acceptable:, the condition of acceptable coverage is specified.

If this condition is not met, the command will exit with exit status 1.

# .octocov.yml
coverage:
  acceptable: 60%

$ octocov
Error: code coverage is 54.9%. the condition in the `coverage.acceptable:` section is not met (`60%`)

By setting codeToTestRatio.acceptable:, the condition of acceptable "Code to Test Ratio" is specified.

If this condition is not met, the command will exit with exit status 1.

# .octocov.yml
codeToTestRatio:
  acceptable: 1:1.2
  code:
    - '**/*.go'
    - '!**/*_test.go'
  test:
    - '**/*_test.go'

$ octocov
Error: code to test ratio is 1:1.1, the condition in the `codeToTestRatio.acceptable:` section is not met (`1:1.2`)

By setting testExecutionTime.acceptable:, the condition of acceptable "Test Execution Time" is specified (on GitHub Actions only) .

If this condition is not met, the command will exit with exit status 1.

# .octocov.yml
testExecutionTime:
  acceptable: 1 min

$ octocov
Error: test execution time is 1m15s, the condition in the `testExecutionTime.acceptable:` section is not met (`1 min`)

By setting *.badge.path:, generate badges self.

# .octocov.yml
coverage:
  badge:
    path: docs/coverage.svg

# .octocov.yml
codeToTestRatio:
  badge:
    path: docs/ratio.svg

# .octocov.yml
testExecutionTime:
  badge:
    path: docs/time.svg

You can display the coverage badge without external communication by setting a link to this badge image in README.md, etc.

# mytool

![coverage](docs/coverage.svg) ![coverage](docs/ratio.svg) ![coverage](docs/time.svg)

By setting push:, git push report badges self.

# .octocov.yml
coverage:
  badge:
    path: docs/coverage.svg
push:

By setting report:, store the reports to datastores and local path.

# .octocov.yml
report:
  datastores:
    - github://owner/coverages/reports
    - s3://bucket/reports

# .octocov.yml
report:
  path: path/to/report.json

• GitHub repository
• GitHub Actions Artifacts
• Amazon S3
• Google Cloud Storage (GCS)
• BigQuery
• Local

By enabling central:, octocov acts as a central repository for collecting reports ( example ).

# .octocov.yml for central mode
central:
  root: .                                  # root directory or index file path of collected coverage reports pages. default: .
  reports:
    datastores:
      - bq://my-project/my-dataset/reports # datastore paths (URLs) where reports are stored. default: local://reports
  badges:
    datastores:
      - local://badges                     # directory where badges are generated.
  push:                                    # enable self git push

This example illustrates how to merge coverage reports from multiple jobs. It is useful when you are testing code branches for multiple targets (e.g. OS, runtime version, dependency version, etc).

# .github/workflows/ci.yml
name: merge coverages from multiple jobs

on:
  push:
    branches:
      - main
      - master
  pull_request:

jobs:
  test:
    strategy:
      fail-fast: true
      matrix:
        include:
          - platform: 'macos-latest'
          - platform: 'ubuntu-latest'
          - platform: 'windows-latest'
    runs-on: ${{ matrix.platform }}
    permissions:
      contents: read # to checkout
    steps:
      - uses: actions/checkout@v4

      - run: YOUR TEST HERE

      - name: Upload coverage to workspace
        uses: actions/upload-artifact@v4
        with:
          path: lcov.info # adjust this path to your coverage file
          name: octocov-${{ matrix.platform }}
          if-no-files-found: error

  coverage-aggregation:
    runs-on: ubuntu-latest
    permissions:
      contents: read # to checkout
      pull-requests: write # for octocov to post comments
      actions: read # for octocov to parse test execution time
    needs:
      - test
    steps:
      - uses: actions/checkout@v4

      - uses: actions/download-artifact@v5
        with:
          pattern: octocov-*

      - uses: k1LoW/octocov-action@v1

# .octocov.yml
codeToTestRatio:
  code:
    - '**/*.go'
    - '!**/*_test.go'
  test:
    - '**/*_test.go'
coverage:
  paths:
    # Name of artifacts uploaded by the test-running jobs.
    # lcov.info (or equivalent) will be downloaded in the directory named after the below.
    - "octocov-windows-latest"
    - "octocov-ubuntu-latest"
    - "octocov-macos-latest"
comment:
  if: is_pull_request
  hideFooterLink: true
  deletePrevious: true
summary:
  if: true
report:
  if: is_default_branch
  datastores:
    - artifact://${GITHUB_REPOSITORY}
diff:
  datastores:
    - artifact://${GITHUB_REPOSITORY}

• GitHub repository
• GitHub Actions Artifacts
• Amazon S3
• Google Cloud Storage (GCS)
• BigQuery
• Local

octocov ls-files command can be used to list files logged in code coverage report.

octocov view (alias: octocov cat) command can be used to view the file coverage report.

The name of the repository.

It should be in the format owner/repo.

By default, the value of the environment variable GITHUB_REPOSITORY is set.

In case of monorepo, code metrics can be reported to datastore separately by specifying owner/repo/project-a or owner/repo@project-a.

repository: k1LoW/octocov

Timeout for octocov execution. (default: 30sec)

timeout: 5min

Configuration for code coverage.

coverage.path: has been deprecated. Please use coverage.paths: instead.

The path to the coverage report file.

If no path is specified, the default path for each coverage format will be scanned.

coverage:
  paths:
    - tests/coverage.xml

Exclude files from the coverage report.

coverage:
  exclude:
    - 'cmd/*.ts'
    - 'proto/**/*.pb.ts'

acceptable coverage condition.

coverage:
  acceptable: 60%

coverage:
  acceptable: current >= 60% && diff >= 0.5%

The variables that can be used are as follows.

It is also possible to omit the expression as follows

Set this if want to generate the badge self.

The path to the badge.

coverage:
  badge:
    path: docs/coverage.svg

Conditions for measuring code coverage.

coverage:
  if: is_default_branch

Configuration for code to test ratio.

Files to count.

codeToTestRatio:
  code:                  # files to count as "Code"
    - '**/*.go'
    - '!**/*_test.go'
  test:                  # files to count as "Test"
    - '**/*_test.go'

acceptable ratio condition.

codeToTestRatio:
  acceptable: 1:1.2

codeToTestRatio:
  acceptable: current >= 1.2 && diff >= 0.0

The variables that can be used are as follows.

It is also possible to omit the expression as follows

Set this if want to generate the badge self.

The path to the badge.

codeToTestRatio:
  badge:
    path: docs/ratio.svg

Conditions for measuring code to test ratio.

codeToTestRatio:
  if: is_default_branch

Configuration for test execution time.

acceptable time condition.

testExecutionTime:
  acceptable: 1min

testExecutionTime:
  acceptable: current <= 1min && diff <= 1sec

The variables that can be used are as follows.

It is also possible to omit the expression as follows

The name of the step to measure the execution time.

testExecutionTime:
  steps:
    - Run test
    - Run slow test

If not specified, the step where the coverage report file is generated is used as the measurement target.

Set this if want to generate the badge self.

The path to the badge.

testExecutionTime:
  badge:
    path: docs/time.svg

Conditions for measuring test execution time.

testExecutionTime:
  if: is_pull_request

Configuration for git push files self.

Conditions for pushing files.

# .octocov.yml
push:
  if: is_default_branch

The variables available in the if section are here.

message for commit.

# .octocov.yml
push:
  message: Update by octocov [skip ci]

Set this if want to comment report to pull request

Hide footer octocov link.

comment:
  hideFooterLink: true

Delete previous code metrics report comments instead of hiding them

comment:
  deletePrevious: true

Add message to code metrics report comments.

comment:
  message: See [coverage html](https://github.com/k1LoW/octocov).

Conditions for commenting report.

# .octocov.yml
comment:
  if: is_pull_request

The variables available in the if section are here.

Set this if want to add report to job summary page.

Hide footer octocov link.

summary:
  hideFooterLink: true

Add message to report.

summary:
  message: See [coverage html](https://github.com/k1LoW/octocov).

Conditions for adding report to job summary page.

# .octocov.yml
summary:
  if: true

The variables available in the if section are here.

Set this if want to insert report to body of pull request.

Hide footer octocov link.

body:
  hideFooterLink: true

Add message to report.

body:
  message: See [coverage html](https://github.com/k1LoW/octocov).

Conditions for inserting report body of pull request.

# .octocov.yml
body:
  if: is_pull_request

The variables available in the if section are here.

Configuration for comparing reports.

Path of the report to compare.

diff:
  path: path/to/coverage.yml

diff:
  path: path/to/report.json

Datastores where the report to be compared is stored.

diff:
  datastores:
    - local://.octocov       # Use .octocov/owner/repo/report.json
    - s3://my-bucket/reports # Use s3://my-bucket/reports/owner/repo/report.json

Conditions for comparing reports

# .octocov.yml
diff:
  if: is_pull_request
  path: path/to/report.json

The variables available in the if section are here.

Configuration for reporting to datastores.

Path to save the report.

report:
  path: path/to/report.json

Datastores where the reports are stored.

report:
  datastores:
    - github://owner/coverages/reports
    - s3://bucket/reports

Use github:// scheme.

github://[owner]/[repo]@[branch]/[prefix]

Required environment variables:

• GITHUB_TOKEN or OCTOCOV_GITHUB_TOKEN
• GITHUB_REPOSITORY or OCTOCOV_GITHUB_REPOSITORY
• GITHUB_API_URL or OCTOCOV_GITHUB_API_URL (optional)

Use artifact:// or artifacts:// scheme.

artifact://[owner]/[repo]/[artifactName]

• artifact://[owner]/[repo]/[artifactName]
• artifact://[owner]/[repo] ( default artifactName: octocov-report )

Note that reporting to the artifact can only be sent from the GitHub Actions of the same repository.

Required environment variables:

• GITHUB_TOKEN or OCTOCOV_GITHUB_TOKEN
• GITHUB_REPOSITORY or OCTOCOV_GITHUB_REPOSITORY
• GITHUB_API_URL or OCTOCOV_GITHUB_API_URL (optional)

Use s3:// scheme.

s3://[bucket]/[prefix]

Required permission:

• s3:PutObject

Required environment variables:

• AWS_ACCESS_KEY_ID or OCTOCOV_AWS_ACCESS_KEY_ID
• AWS_SECRET_ACCESS_KEY or OCTOCOV_AWS_SECRET_ACCESS_KEY
• AWS_SESSION_TOKEN or OCTOCOV_AWS_SESSION_TOKEN (optional)

Use gs:// scheme.

gs://[bucket]/[prefix]

Required permission:

• storage.objects.create
• storage.objects.delete

Required environment variables:

• GOOGLE_APPLICATION_CREDENTIALS or GOOGLE_APPLICATION_CREDENTIALS_JSON or OCTOCOV_GOOGLE_APPLICATION_CREDENTIALS or OCTOCOV_GOOGLE_APPLICATION_CREDENTIALS_JSON

Use bq:// scheme.

bq://[project ID]/[dataset ID]/[table]

Required permission:

• bigquery.datasets.get
• bigquery.tables.get
• bigquery.tables.updateData

Required environment variables:

• GOOGLE_APPLICATION_CREDENTIALS or GOOGLE_APPLICATION_CREDENTIALS_JSON or OCTOCOV_GOOGLE_APPLICATION_CREDENTIALS or OCTOCOV_GOOGLE_APPLICATION_CREDENTIALS_JSON

Datastore schema:

Datastore schema

If you want to create a table, execute the following command ( require bigquery.datasets.create ).

$ octocov migrate-bq-table

Note: Only works with report.datastores or central.reReport.datastores

Use mackerel:// or mkr:// scheme.

mackerel://[Service Name]

Required permission:

• read
• write

Required environment variables:

• MACKEREL_API_KEY or OCTOCOV_MACKEREL_API_KEY

Use local:// or file:// scheme.

local://[path]

Example:

If the absolute path of .octocov.yml is /path/to/.octocov.yml

• local://reports ... /path/to/reports directory
• local://./reports ... /path/to/reports directory
• local://../reports ... /path/reports directory
• local:///reports ... /reports directory.

Conditions for storing a report.

# .octocov.yml
report:
  if: env.GITHUB_REF == 'refs/heads/main'
  datastores:
    - github://owner/coverages/reports

The variables available in the if section are here.

Note: It supports expr-lang/expr expressions.

The variables available in the if section are as follows

Note: When central mode is enabled, other functions are automatically turned off.

The root directory or index file ( index file example ) path of collected coverage reports pages. default: .

central:
  root: path/to

Datastore paths (URLs) where reports are stored. default: local://reports

central:
  reports:
    datastores:
      - local://reports
      - gs://my-gcs-bucket/reports

When using GitHub Actions Artifacts as a datastore, perform badge generation via on.schedule.

# .octocov.yml
report:
  datastores:
    - artifact://${GITHUB_REPOSITORY}

# .octocov.yml for central repo
central:
  reports:
    datastores:
      - artifact://owner/repo
      - artifact://owner/other-repo
      - artifact://owner/another-repo
      [...]
  push:

Code metrics and badges of my open source projects using octocov central mode is here.

Template repositoty is here.

When using the central repository as a datastore, perform badge generation via on.push.

# .octocov.yml
report:
  datastores:
    - github://owner/central-repo/reports

# .octocov.yml for central repo
central:
  reports:
    datastores:
      - github://owner/central-repo/reports
  push:

or

# .octocov.yml for central repo
central:
  reports:
    datastores:
      - local://reports
  push:

When using the S3 bucket as a datastore, perform badge generation via on.schedule.

# .octocov.yml
report:
  datastores:
    - s3://my-s3-bucket/reports

# .octocov.yml for central repo
central:
  reports:
    datastores:
      - s3://my-s3-bucket/reports
  push:

Required permission (Central Repo):

• s3:GetObject
• s3:ListObject

Required environment variables (Central Repo):

• AWS_ACCESS_KEY_ID or OCTOCOV_AWS_ACCESS_KEY_ID
• AWS_SECRET_ACCESS_KEY or OCTOCOV_AWS_SECRET_ACCESS_KEY
• AWS_SESSION_TOKEN or OCTOCOV_AWS_SESSION_TOKEN (optional)

When using the GCS bucket as a datastore, perform badge generation via on.schedule.

# .octocov.yml
report:
  datastores:
    - gs://my-gcs-bucket/reports

# .octocov.yml for central repo
central:
  reports:
    datastores:
      - gs://my-gcs-bucket/reports
  push:

Required permission (Central Repo):

• storage.objects.get
• storage.objects.list
• storage.buckets.get

Required environment variables (Central Repo):

• GOOGLE_APPLICATION_CREDENTIALS or GOOGLE_APPLICATION_CREDENTIALS_JSON or OCTOCOV_GOOGLE_APPLICATION_CREDENTIALS or OCTOCOV_GOOGLE_APPLICATION_CREDENTIALS_JSON

When using the BigQuery table as a datastore, perform badge generation via on.schedule.

# .octocov.yml
report:
  datastores:
    - bq://my-project/my-dataset/reports

# .octocov.yml for central repo
central:
  reports:
    datastores:
      - bq://my-project/my-dataset/reports
  push:

Required permission (Central Repo):

• bigquery.jobs.create
• bigquery.tables.getData

Required environment variables (Central Repo):

• GOOGLE_APPLICATION_CREDENTIALS or GOOGLE_APPLICATION_CREDENTIALS_JSON or OCTOCOV_GOOGLE_APPLICATION_CREDENTIALS or OCTOCOV_GOOGLE_APPLICATION_CREDENTIALS_JSON

Datastore paths (URLs) where badges are generated. default: local://badges

central:
  badges:
    datastores:
      - local://badges
      - s3://my-s3-buckets/badges

Configuration for git push index file and badges self.

Conditions for central mode.

# .octocov.yml
central:
  if: env.GITHUB_REF == 'refs/heads/main'
  reports:
    datastores:
      - s3://my-s3-bucket/reports

The variables available in the if section are here.

Store collected reports in yet another datastores.

Conditions for re storing reports.

Datastores where the reports are re-stored.

octocov supports multiple coverage report formats.

And octocov searches for the default path for each format.

If you want to specify the path of the report file, set coverage.path

coverage:
  paths:
    - /path/to/coverage.txt

Default path: coverage.out

Default path: coverage/lcov.info

Support SF DA only

Default path: coverage/.resultset.json

Default path: coverage.xml

Default path: coverage.xml

Default path: build/reports/jacoco/test/jacocoTestReport.xml

• Code Coverage
• Code to Test Ratio
• Test Execution Time (on GitHub Actions only)

octocov accepts custom metrics in addition to the three supporting metrics.

Specify the path to the custom metrics JSON file in an environment variable prefixed with OCTOCOV_CUSTOM_METRICS_ to collect the code metrics at the same time.

The JSON schema for custom metrics can be found here.

If there are multiple custom metrics JSON files, specify each file path in a separate environment variable (example here) or combine the JSONs that satisfy the JSON schema into an array.

You can set acceptable conditions for custom metrics using the acceptables array within your JSON file.

JSON file format with acceptables:

{
  "key": "performance_metrics",
  "name": "Performance Metrics",
  "metrics": [
    {
      "key": "response_time",
      "name": "Response Time",
      "value": 250.0,
      "unit": "ms"
    },
    {
      "key": "throughput",
      "name": "Throughput",
      "value": 1500.0,
      "unit": "req/s"
    },
    {
      "key": "error_rate",
      "name": "Error Rate",
      "value": 0.5,
      "unit": "%"
    }
  ],
  "acceptables": [
    "current.response_time < 300",
    "current.throughput > 1000",
    "current.error_rate < 1.0",
    "current.response_time <= prev.response_time"
  ]
}

Available variables in acceptables conditions:

If conditions are not met:

$ octocov
Error: custom metrics "performance_metrics" not acceptable condition (`current.response_time < 300`)

octocov detect pull request number following order.

1. Get pull request number from GITHUB_PULL_REQUEST_NUMBER or OCTOCOV_GITHUB_PULL_REQUEST_NUMBER.
2. Get pull request number from GITHUB_REF ( e.g. refs/pull/1/merge ).
3. Get branch name from GITHUB_REF ( e.g. refs/heads/branch/branch/name ) and detect pull request number using GitHub API.

If an environment variable with prefix OCTOCOV_ is set, it is used as an unprefixed environment variable in octocov.

For example, if OCTOCOV_GITHUB_REF is set, it is handled as GITHUB_REF in octocov.

This feature allows environment variables that cannot normally be overridden to be changed on octocov.

deb:

$ export OCTOCOV_VERSION=X.X.X
$ curl -o octocov.deb -L https://github.com/k1LoW/octocov/releases/download/v$OCTOCOV_VERSION/octocov_$OCTOCOV_VERSION-1_amd64.deb
$ dpkg -i octocov.deb

RPM:

$ export OCTOCOV_VERSION=X.X.X
$ yum install https://github.com/k1LoW/octocov/releases/download/v$OCTOCOV_VERSION/octocov_$OCTOCOV_VERSION-1_amd64.rpm

apk:

$ export OCTOCOV_VERSION=X.X.X
$ curl -o octocov.apk -L https://github.com/k1LoW/octocov/releases/download/v$OCTOCOV_VERSION/octocov_$OCTOCOV_VERSION-1_amd64.apk
$ apk add octocov.apk

homebrew tap:

$ brew install k1LoW/tap/octocov

aqua:

$ aqua g -i k1LoW/octocov

manually:

Download binary from releases page

go install:

$ go install github.com/k1LoW/octocov@latest

docker:

$ docker pull ghcr.io/k1low/octocov:latest