Emma:Java代码覆盖率工具

这里主要结合几篇文章分享一下个人理解的emma的简单使用。复杂功能还需要以后进一步学习。

 主页： http://emma.sourceforge.net

详细文档介绍：http://emma.sourceforge.net/reference/reference.html

这篇文章中介绍的Emma比较清晰，本文主要内容来自于它：http://nitintalk.wordpress.com/tag/jar-instrumentation-with-emma/

Emma配置

Emma比较简洁，主要包含emma.jar和emma_ant.jar。

1. 拷贝这两个文件到jdk安装目录的jre/lib/ext下面，然后就可以在命令行尝试命令“java emma”并且显示成功（据介绍这种方式并不会带来对其他项目的影响，因为这两包比较独立）

2. 将emma.jar加入到classpath中。运行命令如“java -cp emma.jar emma *"

Emma使用

Emma使用方式共分为两种：

i) On-the-fly instrumentation

ii) Offline instrumentation

On-the-fly instrumentation

适合java命令通过命令行运行。简单例子：

1)    用emma运行可执行jar文件

Format    : java -cp emma.jar emmarun -jar <executable jar> <jvm arguments>

Example : java -cp emma.jar emmarun -jar /Developer/Examples/Java/JFC/SwingSet2/SwingSet2.jar

它会产生coverage.txt.

2)    With executable jar and extra jars to be instrumented for code coverage

Format  : java -cp emma.jar emmarun -cp <List of jars> -jar <executable jar> <jvm arguments>

By default we get text report in the current directory as “coverage.txt”

3)    To generate HTML report/xml report make use of “-report  html” or “-report xml” option for emmarun as follows :

Example : java -cp emma.jar emmarun -report html -jar /Developer/Examples/Java/JFC/SwingSet2/SwingSet2.jar

4)    If you want to include/exclude specific java packages then you can make use of -ix option for emmarun as follows

Format : java -cp emma.jar emmarun -report html -ix +com.comapany.product.parser.* -cp <classPath> <main class> <jvm arguments>

&nbsp;   It supports wild characters(*,?). Multiple inclusions can be made separated by comma.

To include the package prepend it with ‘+’ otherwise ‘-’. Default nature is ‘+’.

5) You want to attach the source code with html report, use -sp or -sourcepath option for emmarun as follows :

Format : java -cp emma.jar emmarun -report html -ix com.yahoo.pacman.parser.* -sp <sourcePath>-cp <classPath> <main class> <jvm arguments>

Source path should not include the package path, it should be only top level directory. For example if you have package org.apache.xyz  and source directory is dir1/dir2/dir3/org/apache/xyz then use only dir1/dir2/dir3/ in -sp

Offline Instrumentation

On-the-fly as we’ve done above isn’t always possible. For example, a J2EE container could do its own fancy class loading, which is not easy to hook into. Well, in such case EMMA’soffline instrumentation is the solution.

Here instrumentation and report generation is done in 3 steps :

1) Instrument the application jars which you want to check for code coverage

2) Now run application using these instrumented jars

3) Use emma to generate the final report

1) Instrumenting your jars

Basic Command format : java -cp emma.jar emma instr -m overwrite -cp <jars>

This will generate coverage.em which contains some emma metadata information related to instrumented classes. Jars now will have instrumented classes. （参考：http://emma.sourceforge.net/reference/ch02s03.html）

Some options with emma instr :

-ip, -cp, -instrpath <class directories and zip/jar files>

{required} instrumentation path

-d, -dir, -outdir <directory>

instrumentation output directory (required for non-overwrite output modes)

-out, -outfile <file>

metadata output file (defaults to ‘coverage.em’).If you wish to generate the metadata file somewhere else then the current directory then you could use this.

-merge (y[es]|n[o])

default is yes, i.e. metadata will be merged if the metadata file already exists

n[o] can be used to avoid the above behavior

-m, -outmode (copy|overwrite|fullcopy)

output mode (defaults to ‘copy’)

overwrite will overwrite the original jar with instrumented jar

fullcopy can be used with -d option only. This helps in avoiding the overwrite and we get the instrumented jars at specified path.

copy also works with -d option. Difference here is that complete instrumented jar is not produced instead instrumented classes will be created in the package directories under the directory specified for option -d.

-ix, -filter <class name wildcard patterns>

coverage inclusion/exclusion patterns {?,*}

prepend + to package expression to include it and – to exclude. If no symbol is used then specified package will be included

Example: 

java -cp emma.jar emma instr -m fullcopy -ip *.jar -ix -com.google.x.*,-com.google.pig.* -d out
           

Note : If your application happen to be a web app then start restart the web app server after instrumenting your jars.

2) Running your Application

Now you just have to run your program with instrumented jars(don’t forget to put emma jar in the classpath). you need to run program as ur normal java program only as follows :

java -cp emma.jar: jars>:<other jars> -jar <executable jar> arguments

OR

java -cp emma.jar: jars>:<other jars> <className> arguments

Note: try to follow the sequence in which jars have been put in the jvm class path

Once you have stopped using your application and it has been stopped, you will find another emma file coverage.ec which has runtime coverage data.

3 Generating Report

Basic Command format : java -cp emma.jar emma report

Some options with emma report :

-in, -input <list of files>

{required} list of comma separated meta/coverage data files

-r, -report <list of {txt|html|xml}>

{required} coverage report type list

If multiple formats are required then -r can be accompanied with comma separated values.

-sp, -sourcepath <list of source directories>

Java source path for generating reports. Make sure the path should not include the package directories, it has to be top level directory.

Example :

java -cp emma.jar emma report -r html -in coverage.em,coverage.ec

如果内存不够，可以尝试：java -Xmx500m -Xms256m emma instr -m fullcopy -d outinstr -ip *.jar

详情参考 http://emma.sourceforge.net/userguide/ar01s02s03.html

修改Emma的端口号

默认情况下，Emma会使用自身的配置信息，它们被存放在emma.jar包里面的emma_default.properties文件里。有时候我们可能需要对它默认的信息做修改。比如端口号（47653为默认，通常用默认的就行了，我现在是在同一台机器上有两个WebServer，里面都运行着Emma，所以端口会发生冲突。

一种方案是直接修改emma_default.properties。 但这个是不推荐的。

另一种是对需要监控的程序启动时候添加-D参数。如：-Demma.rt.control.port=57653

补充点：

1. Emma如果已经启动了一个程序，想再启动一个可能会出现“java.net.BindException:Address already in use” 的错误。可以尝试Jacoco工具。http://www.eclemma.org/jacoco/

2. Emma的Instrument方式介绍 http://www.taobaotest.com/blogs/show/755