For Codecov to operate properly, all files paths in the coverage report must match the git/hg 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. This can lead to problems, however, 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/hg. 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/hg file structure. If not, you can attempt to apply a path fix and see if this helps on subsequent commits.
Automatic 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.
Disabling default path fixing
To disable Codecov's built-in path fixing, you can add the following to your codecov.yml file.
Manual Path Fixes
Global Path Changes
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/hg structure.
Teams can update a repo level codecov.yml to concretely specify:
- <files in coverage report>::<corresponding paths in git/hg project>
The path fixing options are as follows:
- "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:
The pattern above will move files in the following manner.
As a concrete use case, using the CircleCI example above, Codecov provides the following path fix automatically for CircleCI users:
Conditional Path Changes
In some cases, you only want to modify the paths of certain directories instead of applying the changes across all paths in the report. For example, you want to change a path that shows as repo/src to read repo/package/src. This would be extremely helpful in a monorepo, where you have several packages with the same inner directory structure.
To do this, you could add a path fix rule such as:
This one: `- "^repo/src::repo/package/src"` says that
if the path starts with `repo/src` (the ^ means there can't be anything before it),
then replace `repo/src` with `repo/package/src`
In this way, we are prefixing any paths that start with repo/src with repo/package/src, but ONLY if the path starts with repo/src, so a path like `server/repo/src` will remain untouched.