Viscount — A Direct Method Call Coverage for Java Project

This repository contains the code for Viscount. It is a tool designed to analyze Java test suites by measuring the extent to which test cases directly invoke methods in the production code, categorized by their visibility levels --- public APIs or non-public methods (protected, package-private, private). This analysis helps identify tests that may be tightly coupled to implementation details, which is generally discouraged in unit testing practices. It uses dynamic Java bytecode instrumentation (Javassist) to execute and analyze the test code, and static analysis (Spoon) to examine production code method visibility.

Full Research Paper - (ICSME'24 Research Track)

Viscount Demo Paper - (ICSME'24 Tool Demo Track)

Requirements

• Java 8
• Maven 3
• Python3
• pip3 install -r requirements.txt
• Maven-build project

Optional: Docker

Demo tutorial

Run

Docker

Viscount can be called using Docker (container image - executable without root privilege, without the need to install any additional dependencies natively) as follows:

docker build -t viscount-image .

docker run -v <path_to_project_folder>:/home/user/<project_folder> \
  -v <path_to_report_folder>:/home/user/<reportfolder> \
  viscount-image <project_name> /home/user/<projectfolder> /home/user/<reportfolder>

Requirements - maven:3-open-jdk-8 image

Execution Without Docker

Setting up the environment variables is required:

1. MAVEN_HOME="PATH_TO_MVN"
2. JAVA_HOME="PATH_TO_JAVAJDK"

The main entry point of the tool is viscount.sh.

bash viscount.sh project-name /full/path/to/<project-name> /full/path/to/<reportfolder>

Output

The output is two TSV files and a direct method call coverage (PDF) report in the <reportfolder>

Running example

By simply running viscount-example,

bash viscount.sh viscount-example /viscount/repo/directory/viscount-example /viscount/repo/directory/result

you can also clone square-javapoet and run

bash viscount.sh javapoet /viscount/repo/directory/javapoet /viscount/repo/directory/result

another way is to follow the steps to run using Docker.

How to Contribute

To contribute to our work at unittesting-nonpublic/viscount, please follow these steps:

1. Fork and Clone: Fork the repository to your GitHub account, and clone it to your local machine.
2. Create a branch: In your forked repository, create a new branch with a descriptive name. Make your changes and ensure your commit messages clearly describe them.
3. Push and Resolve Conflicts: Push your changes to the new branch in your fork. Compare your branch with the main branch of this repository, and resolve any conflicts.
4. Submit a draft pull request from your branch. In the description, link it to any related issues.

We appreciate any contributions!