diff options
Diffstat (limited to 'doc/cmd.rst')
| -rw-r--r-- | doc/cmd.rst | 50 |
1 files changed, 32 insertions, 18 deletions
diff --git a/doc/cmd.rst b/doc/cmd.rst index 1344d20e..3551e90d 100644 --- a/doc/cmd.rst +++ b/doc/cmd.rst @@ -219,8 +219,24 @@ To erase the collected data, use the **erase** command:: Combining data files -------------------- -If you need to collect coverage data from different machines or processes, -coverage.py can combine multiple files into one for reporting. +Often test suites are run under different conditions, for example, with +different versions of Python, or dependencies, or on different operating +systems. In these cases, you can collect coverage data for each test run, and +then combine all the separate data files into one combined file for reporting. + +The **combine** command knows how to read a number of separate data files, +match the data by source file name, and write a combined data file with all of +the data. + +Coverage normally writes data to a filed named ".coverage". The ``run +--parallel-mode`` switch (or ``[run] parallel=True`` configuration option) +tells coverage to expand the file name to include machine name, process id, and +a random number so that every data file is distinct:: + + .coverage.Neds-MacBook-Pro.local.88335.316857 + .coverage.Geometer.8044.799674 + +You can also define a new data file name with the ``[run] data_file`` option. Once you have created a number of these files, you can copy them all to a single directory, and use the **combine** command to combine them into one @@ -237,10 +253,9 @@ current directory isn't searched if you use command-line arguments. If you also want data from the current directory, name it explicitly on the command line. -When coverage.py looks in directories for data files to combine, even the -current directory, it only reads files with certain names. It looks for files -named the same as the data file (defaulting to ".coverage"), with a dotted -suffix. Here are some examples of data files that can be combined:: +When coverage.py combines data file, it looks for files named the same as the +data file (defaulting to ".coverage"), with a dotted suffix. Here are some +examples of data files that can be combined:: .coverage.machine1 .coverage.20120807T212300 @@ -251,20 +266,19 @@ An existing combined data file is ignored and re-written. If you want to use runs, use the ``--append`` switch on the **combine** command. This behavior was the default before version 4.2. -The ``run --parallel-mode`` switch automatically creates separate data files -for each run which can be combined later. The file names include the machine -name, the process id, and a random number:: - - .coverage.Neds-MacBook-Pro.local.88335.316857 - .coverage.Geometer.8044.799674 +To combine data for a source file, coverage has to find its data +in each of the data files. Different test runs may run the same source file +from different locations. For example, different operating systems will use +different paths for the same file, or perhaps each Python version is run from a +different subdirectory. Coverage needs to know that different file paths are +actually the same source file for reporting purposes. -If the different machines run your code from different places in their file -systems, coverage.py won't know how to combine the data. You can tell -coverage.py how the different locations correlate with a ``[paths]`` section in -your configuration file. See :ref:`config_paths` for details. +You can tell coverage.py how different source locations relate with a +``[paths]`` section in your configuration file. See :ref:`config_paths` for +details. -If any data files can't be read, coverage.py will print a warning indicating -the file and the problem. +If any of the data files can't be read, coverage.py will print a warning +indicating the file and the problem. .. _cmd_reporting: |