Pause╱Resume and the Control File

Control File

AltCover uses the file <your coverage report>.acv (so in the default case of that being <working-directory>/coverage.xml that would be <working-directory>/coverage.xml.acv) to control the coverage recording process. In runner mode, this file is created before launching the executable given through its -x parameter, and its presence tells the recorder to write the coverage to file or files of the form <working-directory>/coverage.xml.<digits>.acv which are then processed to fill in the report.

In --save (or the Prepare MSBuild task) mode, the instrumenting process also creates the control file, so subsequent execution of the instrumented code will write to *.<digits>.acv files to be later processed by runner --collect (or Collect task). That step reads all the *.<digits>.acv, updates the coverage report and then deletes all the *.acv files (coverage data and, if present, the control file too).

Pause/Resume

From release 3.0.466 AltCover supports controlling coverage collection to file by manual creation or deletion of the control file during the execution of the instrumented code. If the file is not there, coverage goes to memory, but if it is created during execution, subsequent coverage is written to *.<digits>.acv files, as long as it is present, and stops when it is deleted. So we can do

• --save and delete the file mid-run -- captures start-up and until the file is deleted
• without --save and create the file mid-run -- captures from file creation to the end
• without --save, create and then delete the file mid-run -- captures some part of the execution

and any other combination of on/off switching desired.

While the recording is in paused state, the coverage data can be collected (runner --collect) to a report; in combination with the --outputFile option the report from this interval can be prepared, leaving the system in a clean state to switch on again after the the report is run.

Background

The control file mechanism was used from the 1.6 release on as a simple way of communicating one bit of information to the recorder -- whether to send coverage data to file or memory. Since pausing or resuming just requires a toggle, the existing channel was extended to watch the file throughout the execution of the process, not just at the start.