Add FFPuppet.dump_coverage()

Author: tysmith

src/ffpuppet/core.py

@@ -590,6 +590,22 @@ def cpu_usage(self) -> Generator[Tuple[int, float], None, None]:
         if self._proc_tree is not None:
             yield from self._proc_tree.cpu_usage()
 
+    def dump_coverage(self, timeout: int = 15) -> None:
+        """Signal browser to write coverage data to disk.
+
+        Args:
+            timeout: Number of seconds to wait for data to be written to disk.
+
+        Returns:
+            None
+        """
+        if system() != "Linux":  # pragma: no cover
+            raise NotImplementedError("dump_coverage() is not available")
+        if self._proc_tree is not None:
+            if not self._proc_tree.dump_coverage(timeout=timeout):
+                LOG.warning("Timeout writing coverage data")
+                self.close()
+
     def get_pid(self) -> Optional[int]:
         """Get the browser parent process ID.
 

src/ffpuppet/process_tree.py

@@ -4,18 +4,60 @@
 """ffpuppet process tree module"""
 
 from logging import getLogger
+from os import getenv
+from pathlib import Path
 from platform import system
 from subprocess import Popen
-from time import sleep
+from time import perf_counter, sleep
 from typing import Generator, List, Optional, Tuple
 
+try:
+    from signal import SIGUSR1, Signals
+
+    COVERAGE_SIGNAL: Optional[Signals] = SIGUSR1
+except ImportError:
+    COVERAGE_SIGNAL = None
+
 from psutil import AccessDenied, NoSuchProcess, Process, TimeoutExpired, wait_procs
 
 from .exceptions import TerminateError
 
 LOG = getLogger(__name__)
 
 
+def _last_modified(scan_dir: Path) -> Optional[float]:
+    """Scan directory recursively and find the latest modified date of all .gcda files.
+
+    Args:
+        scan_dir: Directory to scan.
+
+    Returns:
+        Last modified date or None if no files are found.
+    """
+    try:
+        return max(x.stat().st_mtime for x in scan_dir.glob("**/*.gcda"))
+    except ValueError:
+        return None
+
+
+def _writing_coverage(procs: List[Process]) -> bool:
+    """Check if any processes have open .gcda files.
+
+    Args:
+        procs: List of processes to check.
+
+    Returns:
+        True if processes with open .gcda files are found.
+    """
+    for proc in procs:
+        try:
+            if any(x for x in proc.open_files() if x.path.endswith(".gcda")):
+                return True
+        except (AccessDenied, NoSuchProcess):  # pragma: no cover
+            pass
+    return False
+
+
 class ProcessTree:
     """Manage the Firefox process tree. The process tree layout depends on the platform.
     Windows:
@@ -64,6 +106,69 @@ def cpu_usage(self) -> Generator[Tuple[int, float], None, None]:
             except (AccessDenied, NoSuchProcess):  # pragma: no cover
                 continue
 
+    def dump_coverage(self, timeout: int = 15, idle_wait: int = 2) -> bool:
+        """Signal processes to write coverage data to disk. Running coverage builds in
+        parallel that are writing to the same location on disk is not recommended.
+        NOTE: Coverage data is also written when launching and closing the browser.
+
+        Args:
+            timeout: Number of seconds to wait for data to be written to disk.
+            idle_wait: Number of seconds to wait to determine if update is complete.
+
+        Returns:
+            True if coverage is written to disk otherwise False.
+        """
+        assert COVERAGE_SIGNAL is not None
+        assert getenv("GCOV_PREFIX_STRIP"), "GCOV_PREFIX_STRIP not set"
+        assert getenv("GCOV_PREFIX"), "GCOV_PREFIX not set"
+        # coverage output can take a few seconds to start and complete
+        assert timeout > 5
+        cov_path = Path(getenv("GCOV_PREFIX"))  # type: ignore[arg-type]
+        last_mdate = _last_modified(cov_path) or 0
+        signaled = 0
+        # send COVERAGE_SIGNAL (SIGUSR1) to browser processes
+        for proc in self.processes():
+            try:
+                proc.send_signal(COVERAGE_SIGNAL)
+                signaled += 1
+            except (AccessDenied, NoSuchProcess):  # pragma: no cover
+                pass
+        # no processes signaled
+        if signaled == 0:
+            LOG.warning("Coverage signal not sent, no browser processes found")
+            return False
+        # wait for processes to write .gcda files (typically takes ~2 seconds)
+        start_time = perf_counter()
+        last_change = None
+        success = False
+        while self.is_running():
+            # collect latest last modified dates
+            mdate = _last_modified(cov_path) or 0
+            # check if gcda files have been updated
+            now = perf_counter()
+            elapsed = now - start_time
+            if mdate > last_mdate:
+                last_change = now
+                last_mdate = mdate
+            # check if gcda write is complete (wait)
+            if (
+                last_change is not None
+                and now - last_change > idle_wait
+                and not _writing_coverage(self.processes())
+            ):
+                LOG.debug("coverage (gcda) dump took %0.2fs", elapsed)
+                success = True
+                break
+            # check if max duration has been exceeded
+            if elapsed >= timeout:
+                if last_change is None:
+                    LOG.warning("Coverage files not modified after %0.2fs", elapsed)
+                else:
+                    LOG.warning("Coverage file open after %0.2fs", elapsed)
+                break
+            sleep(0.25)
+        return success
+
     def is_running(self) -> bool:
         """Check if parent process is running.
 

src/ffpuppet/test_ffpuppet.py

@@ -960,3 +960,19 @@ def test_ffpuppet_32(mocker):
     assert config_job_object.mock_calls[0] == mocker.call(123, 456)
     assert resume_suspended.call_count == 1
     assert resume_suspended.mock_calls[0] == mocker.call(789)
+
+
+def test_ffpuppet_33(mocker):
+    """test FFPuppet.dump_coverage()"""
+    with FFPuppet() as ffp:
+        ffp._proc_tree = mocker.Mock(spec_set=ProcessTree)
+        ffp._proc_tree.dump_coverage.side_effect = (True, False)
+        if system() == "Linux":
+            # success
+            ffp.dump_coverage()
+            # hang
+            ffp.dump_coverage()
+        else:
+            with raises(NotImplementedError):
+                ffp.dump_coverage()
+        ffp._proc_tree = None

src/ffpuppet/test_process_tree.py

@@ -3,6 +3,8 @@
 # You can obtain one at http://mozilla.org/MPL/2.0/.
 """process_tree.py tests"""
 
+from collections import namedtuple
+from itertools import chain, count, repeat
 from pathlib import Path
 from subprocess import Popen
 from time import sleep
@@ -11,7 +13,7 @@
 from pytest import mark, raises
 
 from .exceptions import TerminateError
-from .process_tree import ProcessTree
+from .process_tree import ProcessTree, _last_modified, _writing_coverage
 
 TREE = Path(__file__).parent / "resources" / "tree.py"
 
@@ -169,3 +171,77 @@ def test_process_tree_04(mocker):
     assert stats
     assert stats[0][0] == 1234
     assert stats[0][1] == 2.3
+
+
+@mark.parametrize(
+    "procs, last_mod, writing, success",
+    [
+        # no processes
+        (False, repeat(0), False, False),
+        # data written successfully
+        (True, chain([0], repeat(2)), False, True),
+        # data not updated
+        (True, repeat(0), False, False),
+        # data write timeout
+        (True, chain([0], repeat(2)), True, False),
+    ],
+)
+def test_process_tree_05(mocker, procs, last_mod, writing, success):
+    """test ProcessTree.dump_coverage()"""
+    mocker.patch("ffpuppet.process_tree.COVERAGE_SIGNAL", return_value="foo")
+    mocker.patch("ffpuppet.process_tree.getenv", return_value="foo")
+    mocker.patch("ffpuppet.process_tree.perf_counter", side_effect=count(step=0.25))
+    mocker.patch("ffpuppet.process_tree.sleep", autospec=True)
+    mocker.patch("ffpuppet.process_tree._last_modified", side_effect=last_mod)
+    mocker.patch("ffpuppet.process_tree._writing_coverage", return_value=writing)
+
+    # pylint: disable=missing-class-docstring,super-init-not-called
+    class CovProcessTree(ProcessTree):
+        def __init__(self):
+            pass
+
+        def is_running(self) -> bool:
+            return True
+
+        def processes(self, recursive=False):
+            return [] if not procs else [mocker.Mock(spec_set=Process)]
+
+    tree = CovProcessTree()
+    assert tree.dump_coverage() == success
+
+
+def test_last_modified_01(tmp_path):
+    """test ProcessTree._last_modified()"""
+    # scan missing path
+    assert _last_modified(tmp_path / "missing") is None
+    # scan empty path
+    assert _last_modified(tmp_path) is None
+    # scan path without gcda files
+    (tmp_path / "somefile.txt").touch()
+    assert _last_modified(tmp_path) is None
+    # scan nested path with gcda files
+    (tmp_path / "a").mkdir()
+    (tmp_path / "a" / "file.gcda").touch()
+    assert _last_modified(tmp_path) > 0
+
+
+def test_writing_coverage_01(mocker):
+    """test ProcessTree._writing_coverage()"""
+    openfile = namedtuple("openfile", ["path", "fd"])
+    # empty list
+    assert not _writing_coverage([])
+    # no open files
+    proc = mocker.Mock(spec_set=Process, pid=1337)
+    proc.open_files.return_value = ()
+    assert not _writing_coverage([proc])
+    assert proc.open_files.call_count == 1
+    # open test
+    proc.reset_mock()
+    proc.open_files.return_value = (openfile("file.txt", None),)
+    assert not _writing_coverage([proc])
+    assert proc.open_files.call_count == 1
+    # open gcda
+    proc.reset_mock()
+    proc.open_files.return_value = (openfile("file.gcda", None),)
+    assert _writing_coverage([proc])
+    assert proc.open_files.call_count == 1