Introduction

For Codecov to operate correctly, all file paths in the coverage report must match the git file structure. This approach is how Codecov is able to correctly map coverage information in your uploaded coverage reports to the corresponding files in your repository.

It is incredibly common, and encouraged, for users to run tests in their CI environments and then upload coverage directly to Codecov as a step in their CI process. However, this can lead to problems because the paths to files in a coverage report generated during CI will map to the CI's file system. This mapping may not necessarily map to the file structure of your project in git. When this is the case, Codecov will fail to properly process your reports. Codecov's path fixing feature was built to address this problem.

How do I know if I should use Path Fixing?

Generally, if your uploaded reports fail to process, path fixing may help. You should download the coverage report generated within your CI for a particular commit, examine the file paths located within it, and see if they map directly to your git file structure. If not, you can attempt to apply a path fix and see if this helps on subsequent commits.

An Example of Path Fixing

For example, CircleCI, will clone your project to home/circleci/project and run all tests relative to that directory, meaning your generated coverage report will reference a file as /home/circleci/project/path/to/file.py. which doesn't match the path /project/path/to/file.py in your project.

In many cases, such as with CircleCI above, Codecov has internal methods of mapping paths, so the user is never even aware that paths are being modified in order to map coverage information to their project correctly. However, it is impossible for Codecov to do this for every CI and/or build scenario engineering teams may use.

How to Provide Path Fixes Manually

In the event that your files are failing to process, Codecov provides path fixing to allow engineering teams to manually map the file paths in their coverage reports to their project's git structure.

Teams can update a repo level codecov.yml to specify concretely:

- <files in coverage report>::<corresponding paths in git/hg project>

The path fixing options are as follows:

fixes:
  - "before/::after/"  # move path   e.g., "before/path" => "after/path"
  - "::after/"         # move root   e.g., "path/" => "after/path/"
  - "before/::"        # reduce root e.g., "before/path/" => "path/"

Regexp and glob pattern matching are allowed in the fixes:

fixes:
  - "before/tests-*::after/"

The pattern above will move files in the following manner.

before/tests-apples/test.js => after/test.js
before/tests-oranges/test.js => after/test.js
before/app-apples/app.js => before/app-apples/app.js

As a concrete use case, using the CircleCI example above, Codecov provides the following path fix automatically for CircleCI users:

fixes:
   - "/home/circleci/::"

Default path fixing

Codecov performs a number of default path fixes for specific CI providers and situations where we will need to fix the path every single time. Comprehensive examples of the relevant regex below.

Rules that strip out the user specific portion of URLs:

"((home|Users)/travis/build/[^\/\n]+/[^\/\n]+/)"
TravisCI specific

"((home|Users)/jenkins/jobs/[^\/\n]+/workspace/)"
Jenkins specific

"(Users/distiller/[^\/\n]+/)"
CircleCI specific

"(home/[^\/\n]+/src/([^\/\n]+/){3})"
Golang specific

"((home|Users)/[^\/\n]+/workspace/[^\/\n]+/[^\/\n]+/)"
Jenkins specific

"(.*/jenkins/workspace/[^\/\n]+/)"
Jenkins specific rule not assuming a user or home path root

"((.+/src/)?github\.com/[^\/\n]+/[^\/\n]+/)"
Golang specific rule to strip out the github portion of a file path

"(\w:/Repos/[^\/\n]+/[^\/\n]+/)"
Windows specific rule to strip paths down to their repo root

"([\w:/]+projects/[^\/\n]+/)"

"(\w:/_build/GitHub/[^\/\n]+/)"

"(build/lib\.[^\/\n]+/)"

"(home/circleci/code/)"

"(home/circleci/repo/)"

"(vendor/src/.*)"

"(pipeline/source/)"

"(var/snap-ci/repo/)"

"(home/ubuntu/[^\/\n]+/)"

"(.*/site-packages/[^\/\n]+\.egg/)"
python3+

"(.*/site-packages/)"

"(usr/local/lib/[^\/\n]+/dist-packages/)"

"(.*/slather/spec/fixtures/[^\n]*)"

"(.*/target/generated-sources/[^\n]*)"

"(.*/\.phpenv/.*)"

"(.*/Debug-iphonesimulator/ReactiveCocoa\.build/DerivedSources/RA.*)"

"(usr/include/.*)"

"(.*/handlebars\.js/dist/.*)"

"(node_modules/.*)"

"(bower_components/.*)"

"(.*/lib/clang/.*)"

"(.*[\<\>].*)"

"(\w\:\/)"
E:/ C:/

"(.*/mac-coverage/build/src/.*)"

"(opt/.*/dist-packages/.*)"
opt/ros/indigo/lib/python2.7/dist-packages/...

"(.*/iPhoneSimulator.platform/Developer/SDKs/.*)"

"(Applications/Xcode\.app/Contents/Developer/Toolchains/.*)"

"((.*/)?\.?v?(irtual)?\.?envs?(-[^\/\n]+)?/.*/[^\/\n]+\.py$)"

"(Users/[^\/\n]+/Projects/.*/Pods/.*)"

"(Users/[^\/\n]+/Projects/[^\/\n]+/)"

"(home/[^\/\n]+/[^\/\n]+/[^\/\n]+/)"
/home/:user/:owner/:repo/

Disable default path fixing

To disable Codecov's built-in path fixing, you can add the following to your codecov.yml file.

codecov:
  disable_default_path_fixes: true