parasoft/jtest repository overview

⁠Quick reference

• Maintained by: Parasoft⁠
• Where to get help: Parasoft Documentation⁠, Parasoft Forums⁠, or Parasoft Support and Technical Services⁠

⁠What is Parasoft Jtest?

Parasoft Jtest⁠ is a unified, fully integrated testing solution for java software development. Jtest uses a comprehensive set of analysis techniques, including pattern-based static analysis, dataflow analysis, metrics, code coverage, and more, to help you verify code quality and ensure compliance with industry standards, such as CWE, OWASP, and CERT.

⁠What is included in this image

This image is based on Ubuntu Linux and includes:

• Jtest (installed into /opt/parasoft/jtest)
• OpenJDK 11
• Common utilities (git, vim, wget, curl, fontconfig, sudo, openssh-client)

⁠How to use this image

⁠Licensing

• You must accept the Parasoft End User License Agreement (EULA)⁠ to use this product. To accept the EULA, change parasoft.eula.accepted from false to true in the examples below.
• Be sure Parasoft License Server or Parasoft DTP is deployed in your organization.

To license Parasoft Jtest, create a jtestcli.properties configuration file with the license settings:

# Accept the Parasoft EULA to use this product
parasoft.eula.accepted=false

# Specify the license edition or features
jtest.license.network.edition=server_compliance_edition

# For license retrieved from License Server:
license.network.host=<HOST>:<PORT>
license.network.enabled=true

# For license retrieved from DTP Server:
dtp.url=https://<SERVER>:<PORT>
dtp.user=<USER>
dtp.password=<PASSWORD>

The jtestcli.properties file should be placed in one of the following locations accessible inside the running container:

• The Jtest working directory (typically, the root directory of a java project).
• Another location explicitly specified using the Maven or Gradle plugin options: ... -Djtest.settings=/path/to/jtestcli.properties ....
• The /home/parasoft or /opt/parasoft/jtest directory inside the image. See Image customization⁠.

⁠Basic commands

• To run the jtest command line interface:
  $ docker run --rm parasoft/jtest jtestcli
• To run the build tools:
  $ docker run --rm parasoft/jtest ./gradlew clean build $ docker run --rm parasoft/jtest ./mvnw clean install
• To log into the container:
  $ docker run --rm -it parasoft/jtest bash

⁠Running static analysis for a project located inside the container

In this example, a Makefile project is located inside the container. The current working directory ($PWD) will be mounted to the running container, so that the jtestcli.properties configuration file can be accessed by Jtest. Also, the analysis report will be generated in the mounted directory ($PWD/reports).

1. Create and configure the $PWD/jtestcli.properties configuration file (see Licensing⁠).
2. Configure / build the project and run the analysis using jtest gradle plugin in the project root directory (/opt/parasoft/jtest/examples/demo):
   $ docker run --rm -v $PWD:$PWD -w /opt/parasoft/jtest/examples/demo parasoft/jtest ./gradlew clean assemble jtest -Djtest.config="builtin://Recommended Rules" -Djtest.settings=$PWD/jtestcli.properties -Djtest.report=$PWD/reports
3. Review the analysis report in $PWD/reports.

⁠Running static analysis for a project located on the host

In this example, a gradle project is located on the host in the current working directory ($PWD). The directory will be mounted to the running container, so that all project files and the jtestcli.properties configuration file can be accessed by Jtest. Also, the analysis report will be generated in the mounted directory ($PWD/reports).

1. Create and configure the $PWD/jtestcli.properties configuration file (see Licensing⁠).
2. Configure / build the project and run the analysis using jtest gradle plugin in the mounted directory ($PWD):
   $ docker run --rm -v $PWD:$PWD -w $PWD parasoft/jtest ./gradlew clean assemble jtest -I /opt/parasoft/jtest/integration/gradle/init.gradle -Djtest.config="builtin://Recommended Rules" -Djtest.report=$PWD/reports
3. Review the analysis report in $PWD/reports.

⁠Performing unit tests with code coverage analysis

In this example, a gradle project is located inside the container and the code coverage analysis will be enabled for the project. All the following steps will be performed interactively inside the container (alternatively, they all can be automated / scripted).

1. Log into the container:
   $ docker run --rm -it parasoft/jtest bash
2. Create and configure the jtestcli.properties configuration file in the $HOME directory (see Licensing⁠).
3. Go to the project root directory:
   $$ cd /opt/parasoft/jtest/examples/demo
4. Build the application with code coverage enabled:
   $$ ./gradlew clean jtest-agent test jtest -Djtest.config="builtin://Unit Tests"
5. Review the report in /opt/parasoft/jtest/examples/demo/build/reports/jtest.

⁠Image customization

You can customize the Parasoft Jtest image.

This image runs with a pre-defined parasoft user. The user ID and group ID of the parasoft user may not match the user ID and group ID of the user on the host that is attempting to run this image as this can cause problems when mounting directories from the host. Files owned by the user on the host might not be accessible to the parasoft user and vice versa. In particular, the parasoft user may need to read Jtest projects from the host's file system. Similarly, the parasoft user may need to write Jtest report files back to the host's file system. To solve this problem, the user ID and group ID of the parasoft user can be modified to match the user on the host by building a custom image as follows:

FROM parasoft/jtest

# default values, which can be overriden with --build-arg option
ARG HOST_UID=1000
ARG HOST_GID=1000

USER root:root

RUN rm -f /var/log/lastlog /var/log/faillog && \
    ln -s /dev/null /var/log/lastlog && \
    ln -s /dev/null /var/log/faillog && \
    groupmod -g ${HOST_GID} parasoft && \
    usermod -u ${HOST_UID} -g ${HOST_GID} parasoft && \
    chown -h -R ${HOST_UID}:${HOST_GID} /opt/local/parasoft && \
    touch /var/log/lastlog && \
    touch /var/log/faillog

USER parasoft:parasoft

Note: lastlog and faillog are "sparse files" that can be very large in total size. Certain commands like usermod touch those files. They are temporarily linked to /dev/null to prevent them from bloating the image.

Docker build command:

docker build --no-cache --tag jtest-$(id -un) --build-arg HOST_UID=$(id -u) --build-arg HOST_GID=$(id -g) .

The following example shows a Dockerfile for building a Jtest image including:

• git-lfs extension
• gradle 7.6.4 build automation tool
• Jtest integration with lombok
• Jtest configuration file copied into the $HOME directory

FROM parasoft/jtest

ARG GRADLE_VERSION="7.6.4"
# install git-lfs and unzip commands
# be sure to use the 'root' user to install new packages
USER root
RUN yum -y install git-lfs && yum -y install unzip

# install gradle
WORKDIR /opt
RUN wget https://services.gradle.org/distributions/gradle-${GRADLE_VERSION}-bin.zip && \
    unzip gradle-${GRADLE_VERSION}-bin.zip && \
    rm -f gradle-${GRADLE_VERSION}-bin.zip

# integrate Jtest with lombok 
WORKDIR /opt/parasoft/jtest/integration/lombok
RUN java -jar jtest-integration-lombok.jar

# pre-configure parasoft user environment together with Jtest by copying jtestcli.properties into the $HOME directory 
# be sure to restore default 'parasoft' user    
USER parasoft:parasoft
WORKDIR /home/parasoft
ENV PATH="/opt/gradle-${GRADLE_VERSION}/bin:${PATH}"
COPY jtestcli.properties /home/parasoft/

Here is another example of Parasoft Jtest Image customization. In the Dockerfile file below the Jtest Image is extended with Maven 3.8.2 installation.

FROM parasoft/jtest

ARG MAVEN_VERSION="3.8.2"
ARG USER_HOME_DIR=/home/parasoft

# install git-lfs and unzip commands
# be sure to use the 'root' user to install new packages
USER root

RUN yum -y install git-lfs && yum -y install unzip 

# install maven
WORKDIR /opt
RUN wget https://archive.apache.org/dist/maven/maven-3/${MAVEN_VERSION}/binaries/apache-maven-${MAVEN_VERSION}-bin.zip && \
    unzip apache-maven-${MAVEN_VERSION}-bin.zip && \
    rm -f apache-maven-${MAVEN_VERSION}-bin.zip

#copy default settings.xml to ~/m2
RUN mkdir /home/parasoft/.m2 && cp /opt/apache-maven-${MAVEN_VERSION}/conf/settings.xml /home/parasoft/.m2/settings.xml

## Update ./.m2/settings.xml,
RUN sed -i '/<pluginGroups>/a \ \ \ \ <pluginGroup>com.parasoft.jtest</pluginGroup>\n\ \ \ \ <pluginGroup>com.parasoft.jtest.tia</pluginGroup>' /home/parasoft/.m2/settings.xml

RUN sed -i '/<profiles>/a \
  <profile>\n\
    <id>jtest-settings-profile</id>\n\
    <activation>\n\
      <activeByDefault>true</activeByDefault>\n\
    </activation>\n\
    <properties>\n\
      <jtest.home>/opt/parasoft/jtest</jtest.home>\n\
    </properties>\n\
    <pluginRepositories>\n\
      <pluginRepository>\n\
        <id>jtest-local</id>\n\
        <url>file://${jtest.home}/integration/maven</url>\n\
      </pluginRepository>\n\
    </pluginRepositories>\n\
  </profile>' /home/parasoft/.m2/settings.xml

## Fix permissions
RUN chown -h -R parasoft:parasoft ${USER_HOME_DIR}


# pre-configure parasoft user environment together with Jtest by copying jtestcli.properties into the $HOME directory 
# be sure to restore default 'parasoft' user    
USER parasoft:parasoft
WORKDIR /home/parasoft
ENV PATH="/opt/apache-maven-${MAVEN_VERSION}/bin:${PATH}"

COPY jtestcli.properties /home/parasoft/

If you need different version of Java or Maven you can use the following image customization.

## baseline image
FROM parasoft/jtest

## Permissions to create dirs
USER root
ARG USER_HOME_DIR=/home/parasoft

## Install JDK 17
ARG JAVA_VER=17
ARG JDK_VERSION=jdk-17.0.11
ENV JAVA_HOME=${USER_HOME_DIR}/${JDK_VERSION}

## Download Java 17
RUN wget https://download.oracle.com/java/${JAVA_VER}/archive/${JDK_VERSION}_linux-x64_bin.tar.gz \
&& tar xvzf ${JDK_VERSION}_linux-x64_bin.tar.gz -C ${USER_HOME_DIR}

## Update alternatives to use Java 17
RUN update-alternatives --install /usr/bin/java java ${USER_HOME_DIR}/${JDK_VERSION}/bin/java 1 \
&& update-alternatives --install /usr/bin/javac javac ${USER_HOME_DIR}/${JDK_VERSION}/bin/javac 1

ENV PATH="${JAVA_HOME}/bin:${PATH}"

## Install MVN
## Set MVN args
ARG MAVEN_VERSION=3.9.5
ENV MAVEN_HOME=${USER_HOME_DIR}/apache-maven-${MAVEN_VERSION}
ARG BASE_URL=https://apache.osuosl.org/maven/maven-3/${MAVEN_VERSION}/binaries
RUN mkdir -p ${MAVEN_HOME} \
&& curl -fsSL -o /tmp/apache-maven.tar.gz ${BASE_URL}/apache-maven-${MAVEN_VERSION}-bin.tar.gz \
&& tar -xzf /tmp/apache-maven.tar.gz -C ${MAVEN_HOME} --strip-components=1 \
&& rm -f /tmp/apache-maven.tar.gz \
&& ln -s ${MAVEN_HOME}/bin/mvn /usr/bin/mvn

ENV PATH="${MAVEN_HOME}/bin:${PATH}"

## Copy Deps
COPY jtestcli.properties /home/parasoft/jtestcli.properties
COPY .m2 /home/parasoft/.m2

## Update ./.m2/settings.xml,
RUN cd ./.m2
RUN sed -i '/<pluginGroups>/a \ \ \ \ <pluginGroup>com.parsoft.jtest</pluginGroup>\n\ \ \ \ <pluginGroup>com.parasoft.jtest.tia</pluginGroup>' /home/parasoft/.m2/settings.xml

RUN sed -i '/<profiles>/a \
  <profile>\n\
    <id>jtest-settings-profile</id>\n\
    <activation>\n\
      <activeByDefault>true</activeByDefault>\n\
    </activation>\n\
    <properties>\n\
      <jtest.home>/opt/parasoft/jtest</jtest.home>\n\
    </properties>\n\
    <pluginRepositories>\n\
      <pluginRepository>\n\
        <id>jtest-local</id>\n\
        <url>file://${jtest.home}/integration/maven</url>\n\
      </pluginRepository>\n\
    </pluginRepositories>\n\
  </profile>' /home/parasoft/.m2/settings.xml
  
## Fix permissions
RUN chown -h -R parasoft:parasoft ${USER_HOME_DIR}

## Switch user back and configure MVN
USER parasoft
ENV MAVEN_CONFIG="${USER_HOME_DIR}/.m2"

# Define working directory.
WORKDIR ${USER_HOME_DIR}

# Define default command.
CMD ["mvn", "--version"] 

In this case (apart from ARG variables values if needed) you should provide the .m2 folder with settings.xml file included and jtestcli.properties file both located in the same folder as Dockerfile. The content of settings.xml file will be automatically updated to point to Jtest installation contained in image. Building the Docker image is staighforward in this case - it's simple execution of

docker build -t image_name <path_to_Dockerfile_folder>

command in the folder where the Dockerfile is placed. To run the Static Analysis using Jtest and maven follow these steps:

1. After building the image on basis of abovemetioned Dockerfile run the image:

docker run -v local_project_dir:/home/parasoft/example -it image_name:image_tag bash

1. Run the Static Analysis using Jtest:

cd /home/parasoft/example
mvn jtest:jtest -Djtest.settings=/home/parasoft/jtestcli.properties

⁠License

You need to view and agree to the Parasoft End User License Agreement (EULA)⁠ for the software contained in this image.

As with all Docker images, these likely also contain other software which may be under other licenses. As for any pre-built image usage, it is the image user's responsibility to ensure that any use of this image complies with any relevant licenses for all software contained within.