Please visit NCover FAQ for updated information.
- What is code coverage analysis?
- Why would I want to do code coverage analysis?
- What makes NCover better than other code coverage tools?
- Which programming languages does NCover support?
- Does NCover require a special compilation step for my code?
- How does NCover work?
- What kind of output does NCover produce?
- What does the XML output look like?
- Is there a graphical interface? A command line utility?
- How do I use coverage exclusions?
- Can I use NCover with 64-bit programs? How?
- Troubleshooting: Why don't I get coverage for Automatic Properties?
- Troubleshooting: Why is my coverage.xml file empty?
- Troubleshooting: I have coverage.xml output but my XYZ assembly is not included in it?
- Troubleshooting: After running NCover my coverage.log says "Failed to load symbols for module XYZ"?
- Troubleshooting: I get a "Profiled process terminated. Profiler connection not established" message?
- Troubleshooting: My coverage exclusions are not working?
- Troubleshooting: I get a Profiler Not Connected, No Data Collected Exception
- Where can I get additional help or support?
1. What is code coverage analysis?
A code coverage analyzer monitors your code at runtime and records information about which lines of code were executed. NCover shows each sequence point in your application along with the number of times that point was executed. Sequence points are generated by the compiler and stored in the debug information (.pdb) files. A sequence point basically corresponds to a single program statement (often a line of code) in your high-level language.
2. Why would I want to do code coverage analysis?
Unit test suites are often used as a quality tool during the development process to keep the codebase stable as it changes and expands. Tools such as NUnit are often used to run and report on the test suites. However, when implementing unit testing in your build process, you have no way of knowing how much of your code the unit tests are actually testing. This is where code coverage comes in. You can run NUnit within NCover and use the code coverage report to determine which code was not tested by that particular test suite.
3. What makes NCover better than other code coverage tools?
Unlike most code coverage tools, NCover does not modify your source code in any way to generate coverage information. This means that you get coverage based on real, production code, providing more accurate data. For more information about how NCover works, see "Does NCover require a special compilation for my code?" and "How does NCover work?"
4. Which programming languages does NCover support?
In short, NCover supports any .NET programming language. NCover requires the .NET framework version 2.0.50727 to be installed; however, the application being profiled can be written against any shipping version of the framework. NCover has been tested profiling coverage of .NET 3.5, .NET 3.0, .NET 2.0 and .NET 1.1 applications. Note that NCover derives a lot of information from debugging symbols (.PDB files), which are not governed by any standard. This means that different languages and compilers will yield slightly different output.
5. Does NCover require a special compilation step for my code?
No. NCover is designed to work on shipping code by using the .NET Framework profiling API to monitor your code. It does require build symbols, but can be run on release code without any modifications. Note that debugging symbols may not be enabled by default in your particular programming environment. Changing this is typically as simple as adding an additional command line flag or project setting.
6. How does NCover work?
NCover uses the .NET Framework profiling API to monitor an application's execution. When a method is loaded by the CLR, NCover retrieves the IL and replaces it with instrumented IL code. NCover does not change your original IL code; it simply inserts new code to update a visit counter at each sequence point. After the .NET process has shut down the profiler outputs statistics to the coverage file.
7. What kind of output does NCover produce?
By default, NCover outputs an xml file named coverage.xml. This file is the analysis output of NCover which you can load into NCover Explorer to see a graphical representation, including source code highlighting.
Another option available to Complete Edition users is the HTML output command line flag (//h). This generates a redistributable directory structure that can be viewed in any web browser.
8. What does the XML output look like?
Here is an example of the XML output:
<method name="ExternalThrownException" signature="ExternalThrownException() : void" excluded="false" instrumented="true">
<seqpnt vc="1" l="40" el="40" c="17" ec="43" ex="false" fl="65536" doc="1" />
<seqpnt vc="0" l="41" el="41" c="17" ec="59" ex="false" fl="65536" doc="1" />
<seqpnt vc="0" l="16707566" el="16707566" c="0" ec="0" ex="true" fl="197121" doc="1" />
<seqpnt vc="1" l="42" el="42" c="15" ec="34" ex="false" fl="65536" doc="1" />
<seqpnt vc="1" l="43" el="43" c="17" ec="46" ex="false" fl="65536" doc="1" />
<seqpnt vc="0" l="16707566" el="16707566" c="0" ec="0" ex="true" fl="197121" doc="1" />
<seqpnt vc="1" l="45" el="45" c="9" ec="10" ex="false" fl="196608" doc="1" />
</method>9. Is there a graphical interface? A command line utility?
NCover provides both a graphical interface (NCoverExplorer.exe) and a command line utility (NCover.Console.exe) as well as a reporting tool (NCoverExplorer.Console.exe).
10. How do I use coverage exclusion attributes?
First you should define an attribute to markup your excluded code with. You will likely want to put this in a common assembly to make it reusable, or within a "CommonAssemblyInfo.cs" file that you include in all of your application assemblies.
{ { } }
Apply the attribute to the C# classes and/or methods you wish to mark as excluded from code coverage statistics
[CoverageExcludeAttribute]
{}Finally, ensure you pass the full qualified attribute information in the NCover command line:
NCover.Console.exe MyApplication.exe //ea MyNamespace.CoverageExcludeAttributeIMPORTANT: Note that if you are using the TestDriven.Net VS.Net add-in to "Test with Coverage" it will automatically pass through "//ea CoverageExcludeAttribute" which you should define without a namespace like above.
11. Can I use NCover with 64-bit programs? How?
If you are using the Enterprise Edition, yes. To profile 64-bit applications, you must have used the 64-bit installer, available from the download page. Otherwise, it is no different than profiling a regular 32-bit application.
12. Troubleshooting: Why don't I get coverage for Automatic Properties?
Automatic Properties are syntactic sugar supported by the VS 2008 C# compiler. Unfortunately, the compiler doesn't emit any symbols for Automatic Properties, so NCover (since it depends on the symbols generated by the compiler and placed in the PDBs) isn't even aware that an Automatic Property exists. However, NCover does produce Branch Coverage for Automatic Properties. Unfortunately, NCover Explorer and the Full Coverage Report don't highlight Branch Coverage in the source files.
13. Troubleshooting: Why is my coverage.xml file empty?
Your coverage.xml file is empty because NCover was unable to locate the debug symbol files for the assemblies profiled. This could happen because the assemblies were loaded from the GAC, in which case you should either uninstall the assemblies from the GAC, or move the .pdbs into the GAC.
One other reason NCover generates an empty coverage.xml file is because the assemblies were loaded from NUnit's shadow copy. By default, NUnit shadow copies your assemblies before it tests them, and in some cases, the .pdb files aren't copied with the assemblies. The easiest way to fix this problem is to run NUnit with the /noshadow command.
Finally, the //ssp argument might be too restrictive. Grant Drake has an excellent help page on empty coverage.xml files here.
14. Troubleshooting: I have coverage.xml output but my XYZ assembly is not included in it?
- NCover will only profile loaded assemblies - did your code execution path force that assembly to be loaded (e.g. by loading a type or calling a method in that assembly)?
- Did you generate build symbol files (.pdb files) for the missing assembly?
- If using the //a option, did you correctly list the assembly names including the one that is missing?
- Can you see information about the assembly being loaded within the coverage.log? Is the correct assembly being loaded (check the path) - if you have a version in the GAC it may possibly prevent the .pdb file from being loaded.
- If using the NCover Explorer GUI, is a coverage exclusion defined causing it to be hidden from the display?
15. Troubleshooting: After running NCover my coverage.log says "Failed to load symbols for module XYZ"?
This message means that no .pdb build symbol file was found for that assembly so it cannot be profiled for code coverage. If that assembly is part of the .NET framework, for instance, the System.Data dll, then this is an expected message and should not cause concern. If however the assembly belongs to your application, did you generate the build symbol files (.pdb files) for it?
16. Troubleshooting: I get a "Profiled process terminated. Profiler connection not established" message?
This message means that NCover was unable to find the NCover.Lib dll. Run NCover with the //reg argument to force the dll to register so that NCover can find it. Grant Drake offers some advice on this topic here.
17. Troubleshooting: My coverage atribute exclusions are not working?
The //ea argument expects the fully qualified name of the attibute class.
Example:
//ea "MyProject.Utilities.CoverageExcludeAttribute"See the "How do I use coverage exclusions?" question above.
18. Troubleshooting: I get a "Profiler Not Connected, No Data Collected" exception?
Possible causes for this exception include:
- User doesn't have administrative privileges: NCover requires admin privileges to profile.
- User is trying to profile a native application.
- Some WCF services seem to take a long time loading the first IL byte. This can cause an inadvertent timeout in NCover. Recommend using the //wal flag to overcome this problem.
- User is trying to profile a 32-bit application/dll on a 64-bit machine.
- User is tying to profile a 1.1 app/dll on a 64-bit machine. (1.1 doesn't have a 64-bit runtime)
19. Where can I get additional help or support?
If your question is not answered here, we recommend taking a look at the forums. If you still can't find a solution to your issue, you can either post a new thread on the forum or submit a support ticket.