Laravel Tip: Store your test coverage with CodeCov

Photo by Ricardo Resende on Unsplash

Before getting started, I'd love for you to consider checking out my latest venture FlagFox.

Introduction

If you’re not aware Laravel’s artisan test command has been able to generate code coverage reports in the console output for some time now. This is great, but receiving that output in the console only helps a little when you run many of your tests in continuous integration.

This is where CodeCov comes up, a service for keeping track of your application's code coverage over time.

This tutorial will cover Setting up CodeCov and creating a GitHub Action to store the results. Nothing is stopping you from using another CI service with CodeCov, but for publishing results, I'll be using specifically GitHub actions.

Create a CodeCov account

This is straightforward as setups go. You can create an account via GitHub, which makes sense if you're already hosting your repo with GitHub.

At that point, you can search for the git repo you want to collect code coverage for, and upon selecting that repository, you'll see the following screen.

This will stay blank until we start pushing any coverage reports. To do this, we need to create our testing action. On this page, you will see a Token that you'll need to copy if you're setting up a private GitHub repository. Open-source projects can skip the token setup.

Creating a GitHub Action

The first thing to do will be to set up a secret in your GitHub repository. This will be the safest place to keep the token so others won't be able to upload code reports to CodeCov.

You only need to create a new Actions Secret in the repository settings, copy the token into the Secret input, and then save it.

The next part all occurs within our code.

We need to add a .github/workflows/run-tests.yml file to our project's folder. It also should contain the following Yaml file.

Please note that sometimes your tests will have different requirements; you will need to make that work before sending coverage reports. What's important here is the following:

1. Your PHP setup must have a code coverage driver. In the example, it's PCov which, at the moment, is considered the best option for running tests with speed.
2. When we reach the code execution step, we're running PHPUnit (or, in this case, the Artisan Test command) with the coverage options and telling PHPUnit where to save the report.
3. In the project, I've added a /storage/coverage folder and put a .gitignore file so that reports can be generated to that folder but will never be committed to the repository.
4. We're using the CodeCov Github Action they provide to use the token from the secrets we've configured, and we've told it the file we want to upload.

You’ll find that if you have set up the secrets or the actions wrong, the CodeCov upload step will fail silently and require you to look at the action's output to explain why it's failed.

If you've been successful, your code coverage action will look like this:

Now when we go to CodeCov, we should be able to see the output of our actions.

You can browse the results on CodeCov directly for the demo project I created.

Adding that coverage Badge

Of course, what is the point of this all if you won't be showing off that (hopefully green) code coverage?

To do this, we only need to go to the settings of our repo on CodeCov, and then we can copy the provided Markdown.

Once we have this, we can paste it into our project's README.md file.

Once committed, we'll see the badge and click through to the report on Codecov.

Conclusion

Well, we can wrap this up quickly. Code coverage is a great metric to monitor, don't put too much faith in that 100% mark, instead treat the value as a way to track progress or regression. Suppose you find yourself starting with 50% or so. Then it would be best if you aimed to maintain or improve this value. If you see it dropping over the next few months, you can begin to question whether you need to evaluate why that is the case or not.

Either way, I hope you'll have fun getting that feedback. Feel free to tweet me your code coverage on Twitter; I'd love to hear what you got.

Like Always, if you want to see all the code, you can view the repository created on GitHub.

I’m Peter Fox, a UK software developer with a decade of experience with PHP and Laravel. I’ve started work on a new project. Flagfox for Laravel will build upon my already established work creating open-source packages to help developers add feature flags to their applications. We currently have a waiting list for those interested in learning more.