Bitbucket Integration

Projects with the git plugin configured can be setup to run pitest against pull requests on both Bitbucket cloud and self hosted Bitbucket instances. This is a very effective way to use mutation testing. Analysis usually takes only seconds, no matter how large the codebase.

The results are displayed directly in the PR. A comment is created each time changes are pushed, showing a summary of the mutation testing results.

And annotations are added to the diff view for each line of code with surviving mutants.

Bitbucket integration is easiest using Bitbucket Pipelines. Other CI systems are also supported, but require some additional configuration.

Plugins are provided for maven and gradle

Licence

Before you can use the integration, you must first acquire a licence.

Once you have the licence you should place the file it in the root of your git repo. Do not change the name from arcmutate-licence.txt

Maven Configuration For Bitbucket Pipelines

Bitbucket integration is provided by the pitest-bitbucket-maven-plugin

Before configuring the maven plugin, first configure the pitest-git plugin.

The CDG pitest-git plugin and pitest-bitbucket-maven-plugin are always released together, and their version numbers should be kept in sync. This can be achieved by creating a property.

<properties>
  <cdg.pitest.version>2.0.0</cdg.pitest.version>
</properties>

The pitest-bitbucket-maven-plugin can then be added to the pluginManagement section of your pom (or plugins section if it is a single module project).

<plugin>
    <groupId>com.arcmutate</groupId>
    <artifactId>pitest-bitbucket-maven-plugin</artifactId>
    <version>${cdg.pitest.version}</version>
</plugin>

A pipeline can the be created to run pitest against all PRs

image: maven:3.6.3

pipelines:
 pull-requests:
  '**':
   - step:
      name: Build and Test
      caches:
       - maven
      script:
       - export BASE=`git merge-base $BITBUCKET_COMMIT $BITBUCKET_PR_DESTINATION_COMMIT`
       - mvn -B -Ppitest -Dverbose=true -Dfeatures="+GIT(from[$BASE]), +gitci" verify
       - mvn pitest-bitbucket:bitbucket-cloud

The script uses ‘git merge-base’ to find the common ancestor of the latest commit on the PR branch and the branch it is to be merged into, and passes this to the ‘git-plugin’. If you are using a different CI system, this commit may be provided as an environment variable and may not need to be calculated.

The +gitci parameter passed to pitest instructs it to produce additional json output that is read by the pitest-bitbucket plugin.

The parameters required by the pitest-bitbucket plugin are automatically resolved from environment variables. Most of these are provided automatically by pipelines, but authentication parameters must be manually setup as repository variables.

See the maven demo project for a full example of a configured project.

Gradle Configuration

Setup with gradle is similar to maven. See bitbucket gradle plugins for details.

See the gradle demo project for a full example of a configured project.

Authentication

In order to create and update comments on pull requests, the plugins must authenticate with the Bitbucket server.

An access token and (for some authentication types) the username it corresponds to must be supplied. If these are placed in environment variables named :-

• REPO_TOKEN
• REPO_USER

Both the maven and gradle plugins will use these automatically without further configuration. If you do not wish to place these details in environment variables, see the plugin documentation for details of how to configure them.

Bitbucket Cloud

Authentication can either be by access token or app password.

When using an app password, the username the password corresponds to must also be supplied.

App passwords can be created by navigating to Personal Setting/App passwords on Bitbucket.

Both the maven and gradle plugins will assume that access tokens are being used by default. To use an application password, the useAppPassword property must be explicitly set to true.

The token used needs write access to Pull Requests.

Bitbucket Server

A Personal access token can be used to access the api. A token can be created by navigating to Manage Account/Personal access tokens.

The token needs write access to the repository.

GitCi Level

For Bitbucket server, if the optional level parameter of the gitci feature is set to error tasks will be created for each mutant instead of normal comments. The level parameter has no effect for Bitbucket cloud.

e.g.

mvn -Ppitest -Dfeatures="+GIT(from[HEAD~1]), +gitci(level[error])" test