Merge pull request py-cov-action#594 from olivier-lacroix/feat/write-some-outputs

Author: ewjoachim

README.md

@@ -346,6 +346,56 @@ jobs:
           path: python-coverage-comment-action.txt
 ```
 
+### Outputs
+
+The action makes available some data for downstream processing.
+
+| Name | Description |
+| --- | --- |
+| `activity_run` | The type of activity that was run. One of `process_pr`, `post_comment`, `save_coverage_data_files`. |
+
+All the following outputs are only available when running in PR mode.
+
+| Name | Description |
+| --- | --- |
+| `comment_file_written` | A boolean indicating whether a comment file was written to `COMMENT_FILENAME` or not. |
+| `new_covered_lines` | The number of covered lines in the pull request. |
+| `new_num_statements` | The number of statements in the pull request. |
+| `new_percent_covered` | The coverage percentage of the pull request. |
+| `new_missing_lines` | The number of lines with missing coverage in the pull request. |
+| `new_excluded_lines` | The number of excluded lines in the pull request. |
+| `new_num_branches` | The number of branches in the pull request. |
+| `new_num_partial_branches` | The number of partial branches in the pull request. |
+| `new_covered_branches` | The number of covered branches in the pull request. |
+| `new_missing_branches` | The number of branches with missing coverage in the pull request. |
+| `reference_covered_lines` | The number of covered lines in the base branch. |
+| `reference_num_statements` | The number of statements in the base branch. |
+| `reference_percent_covered` | The coverage percentage of the base branch. |
+| `reference_missing_lines` | The number of lines with missing coverage in the base branch. |
+| `reference_excluded_lines` | The number of excluded lines in the base branch. |
+| `reference_num_branches` | The number of branches in the base branch. |
+| `reference_num_partial_branches` | The number of partial branches in the base branch. |
+| `reference_covered_branches` | The number of covered branches in the base branch. |
+| `reference_missing_branches` | The number of branches with missing coverage in the base branch. |
+| `diff_total_num_lines` | The total number of lines in the diff. |
+| `diff_total_num_violations` | The total number of lines with missing coverage in the diff. |
+| `diff_total_percent_covered` | The coverage percentage of the diff. |
+| `diff_num_changed_lines` | The number of changed lines in the diff. |
+
+Usage may look like this
+
+```yaml
+- name: Coverage comment
+  id: coverage_comment
+  uses: py-cov-action/python-coverage-comment-action@v3
+  with:
+    GITHUB_TOKEN: ${{ github.token }}
+
+- name: Enforce coverage
+  if: ${{ steps.coverage_comment.outputs.new_percent_covered < steps.coverage_comment.outputs.reference_percent_covered }}
+  run: echo "Coverage decreased." && exit 1
+```
+
 ### All options
 
 ```yaml

action.yml

@@ -111,13 +111,59 @@ inputs:
       Deprecated, see https://docs.github.com/en/actions/monitoring-and-troubleshooting-workflows/enabling-debug-logging
     default: false
 outputs:
-  COMMENT_FILE_WRITTEN:
-    description: >
-      This output is only set when running in PR mode. It's a boolean indicating
-      whether a comment file was written to COMMENT_FILENAME or not. If so,
-      you'll need to run the action in workflow_run mode to post it. If
-      "false", no comment file was written (likely because the comment was
-      already posted to the PR).
+  activity_run:
+    description: >
+      The type of activity that was run. One of `process_pr`, `post_comment`, `save_coverage_data_files`.
+  comment_file_written:
+    description: >
+      A boolean indicating whether a comment file was written to COMMENT_FILENAME or not.
+      If so, you'll need to run the action in workflow_run mode to post it. If "false",
+      no comment file was written (likely because the comment was already posted to the PR).
+      Only available when running in PR mode.
+  new_covered_lines:
+    description: The number of covered lines in the pull request. (Only available in PR mode)
+  new_num_statements:
+    description: The number of statements in the pull request. (Only available in PR mode)
+  new_percent_covered:
+    description: The coverage percentage of the pull request. (Only available in PR mode)
+  new_missing_lines:
+    description: The number of lines with missing coverage in the pull request. (Only available in PR mode)
+  new_excluded_lines:
+    description: The number of excluded lines in the pull request. (Only available in PR mode)
+  new_num_branches:
+    description: The number of branches in the pull request. (Only available in PR mode)
+  new_num_partial_branches:
+    description: The number of partial branches in the pull request. (Only available in PR mode)
+  new_covered_branches:
+    description: The number of covered branches in the pull request. (Only available in PR mode)
+  new_missing_branches:
+    description: The number of branches with missing coverage in the pull request. (Only available in PR mode)
+  reference_covered_lines:
+    description: The number of covered lines in the base branch. (Only available in PR mode)
+  reference_num_statements:
+    description: The number of statements in the base branch. (Only available in PR mode)
+  reference_percent_covered:
+    description: The coverage percentage of the base branch. (Only available in PR mode)
+  reference_missing_lines:
+    description: The number of lines with missing coverage in the base branch. (Only available in PR mode)
+  reference_excluded_lines:
+    description: The number of excluded lines in the base branch. (Only available in PR mode)
+  reference_num_branches:
+    description: The number of branches in the base branch. (Only available in PR mode)
+  reference_num_partial_branches:
+    description: The number of partial branches in the base branch. (Only available in PR mode)
+  reference_covered_branches:
+    description: The number of covered branches in the base branch. (Only available in PR mode)
+  reference_missing_branches:
+    description: The number of branches with missing coverage in the base branch. (Only available in PR mode)
+  diff_total_num_lines:
+    description: The total number of lines in the diff. (Only available in PR mode)
+  diff_total_num_violations:
+    description: The total number of lines with missing coverage in the diff. (Only available in PR mode)
+  diff_total_percent_covered:
+    description: The coverage percentage of the diff. (Only available in PR mode)
+  diff_num_changed_lines:
+    description: The number of changed lines in the diff. (Only available in PR mode)
 runs:
   using: docker
   image: Dockerfile

coverage_comment/coverage.py

@@ -21,8 +21,20 @@ class CoverageMetadata:
     show_contexts: bool
 
 
+class OutputMixin:
+    def as_output(self, prefix: str) -> dict:
+        data = dataclasses.asdict(self)
+        output = {}
+        for key, value in data.items():
+            if value is not None and not isinstance(value, dict):
+                output[f"{prefix}_{key}"] = (
+                    float(value) if isinstance(value, decimal.Decimal) else value
+                )
+        return output
+
+
 @dataclasses.dataclass(kw_only=True)
-class CoverageInfo:
+class CoverageInfo(OutputMixin):
     covered_lines: int
     num_statements: int
     percent_covered: decimal.Decimal
@@ -76,7 +88,7 @@ def violation_lines(self) -> list[int]:
 
 
 @dataclasses.dataclass(kw_only=True)
-class DiffCoverage:
+class DiffCoverage(OutputMixin):
     total_num_lines: int
     total_num_violations: int
     total_percent_covered: decimal.Decimal

coverage_comment/github.py

@@ -7,6 +7,7 @@
 import re
 import sys
 import zipfile
+from typing import Any
 from urllib.parse import urlparse
 
 from coverage_comment import github_client, log
@@ -209,7 +210,7 @@ def post_comment(
             raise CannotPostComment from exc
 
 
-def set_output(github_output: pathlib.Path | None, **kwargs: bool) -> None:
+def set_output(github_output: pathlib.Path | None, **kwargs: Any) -> None:
     if github_output:
         with github_output.open("a") as f:
             for key, value in kwargs.items():

coverage_comment/main.py

@@ -268,6 +268,12 @@ def process_pr(
             ],
         )
 
+    outputs = {"activity_run": "process_pr"}
+    outputs |= coverage.info.as_output(prefix="new")
+    outputs |= diff_coverage.as_output(prefix="diff")
+    if previous_coverage:
+        outputs |= previous_coverage.info.as_output(prefix="reference")
+
     try:
         if config.FORCE_WORKFLOW_RUN or not pr_number:
             raise github.CannotPostComment
@@ -292,14 +298,16 @@ def process_pr(
             filename=config.FINAL_COMMENT_FILENAME,
             content=comment,
         )
-        github.set_output(github_output=config.GITHUB_OUTPUT, COMMENT_FILE_WRITTEN=True)
+        outputs["comment_file_written"] = True
         log.debug("Comment stored locally on disk")
     else:
-        github.set_output(
-            github_output=config.GITHUB_OUTPUT, COMMENT_FILE_WRITTEN=False
-        )
+        outputs["comment_file_written"] = False
         log.debug("Comment not generated")
 
+    github.set_output(
+        github_output=config.GITHUB_OUTPUT,
+        **outputs,
+    )
     return 0
 
 
@@ -363,6 +371,7 @@ def post_comment(
     )
     log.info("Comment posted in PR")
 
+    github.set_output(github_output=config.GITHUB_OUTPUT, activity_run="post_comment")
     return 0
 
 
@@ -440,4 +449,8 @@ def save_coverage_data_files(
 
     log.info(log_message)
 
+    github.set_output(
+        github_output=config.GITHUB_OUTPUT, activity_run="save_coverage_data_files"
+    )
+
     return 0

tests/integration/conftest.py

@@ -2,6 +2,7 @@
 
 import os
 import pathlib
+import shutil
 import subprocess
 import uuid
 
@@ -50,16 +51,22 @@ def _(*variables):
 
 
 @pytest.fixture
-def commit(integration_dir):
+def git_cmd():
+    return shutil.which("git")
+
+
+@pytest.fixture
+def commit(integration_dir, git_cmd):
     def _():
         subprocess.check_call(
-            ["git", "add", "."],
+            [git_cmd, "add", "."],
             cwd=integration_dir,
         )
         subprocess.check_call(
-            ["git", "commit", "-m", str(uuid.uuid4())],
+            [git_cmd, "commit", "-m", str(uuid.uuid4())],
             cwd=integration_dir,
-            env={
+            env=os.environ
+            | {
                 "GIT_AUTHOR_NAME": "foo",
                 "GIT_AUTHOR_EMAIL": "foo",
                 "GIT_COMMITTER_NAME": "foo",
@@ -73,27 +80,31 @@ def _():
 
 
 @pytest.fixture
-def integration_env(integration_dir, write_file, run_coverage, commit, request):
-    subprocess.check_call(["git", "init", "-b", "main"], cwd=integration_dir)
+def integration_env(
+    integration_dir, write_file, run_coverage, commit, request, git_cmd
+):
+    subprocess.check_call([git_cmd, "init", "-b", "main"], cwd=integration_dir)
     # diff coverage reads the "origin/{...}" branch so we simulate an origin remote
-    subprocess.check_call(["git", "remote", "add", "origin", "."], cwd=integration_dir)
+    subprocess.check_call(
+        [git_cmd, "remote", "add", "origin", "."], cwd=integration_dir
+    )
     write_file("A", "B")
     commit()
 
     add_branch_mark = request.node.get_closest_marker("add_branches")
     for additional_branch in add_branch_mark.args if add_branch_mark else []:
         subprocess.check_call(
-            ["git", "switch", "-c", additional_branch],
+            [git_cmd, "switch", "-c", additional_branch],
             cwd=integration_dir,
         )
 
     subprocess.check_call(
-        ["git", "switch", "-c", "branch"],
+        [git_cmd, "switch", "-c", "branch"],
         cwd=integration_dir,
     )
 
     write_file("A", "B", "C", "D")
     commit()
 
     run_coverage("A", "C")
-    subprocess.check_call(["git", "fetch", "origin"], cwd=integration_dir)
+    subprocess.check_call([git_cmd, "fetch", "origin"], cwd=integration_dir)