# ANT build tool

## Creating a Session ID <a href="#creating-a-session-id" id="creating-a-session-id"></a>

Before running the build scan and tests, you need to create a session ID. The session ID is provided to each step in order to link them together as one complete cycle.

Generating a session ID in Java is done using the Java Build scanner with the `-config` flag. This command can be executed as an ANT Java task.

{% code overflow="wrap" lineNumbers="true" %}

```java
<tstamp>
     <format property="time.stamp" pattern="yyyyMMdd-HHmm"/>
</tstamp>

<target name="sealights_config">
	<java jar="${sealights.dir}/sl-build-scanner.jar" fork="true">
		<arg value="-config"/>
		<arg value="-tokenfile"/>
		<arg value="${sealights.dir}/sltoken.txt"/>
		<arg value="-appname"/>
		<arg value="myApp"/>
		<arg value="-branchname"/>
		<arg value="master"/>
		<arg value="-buildname"/>
		<arg value="${time.stamp}"/>
		<arg value="-pi"/>
		<arg value="*com.company.*"/>
	</java>
</target>
```

{% endcode %}

In the sample code above, we have used a timestamp for the **build name** but **any environment variable** can be used according to **your organization’s naming convention**.

{% hint style="info" %}
See [#inlineextension-creating-a-session-id](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/command-reference#inlineextension-creating-a-session-id "mention") for full parameter details
{% endhint %}

## Scanning a build <a href="#scanning-a-build" id="scanning-a-build"></a>

In order to collect coverage information SeaLights, agents need to first scan the binary files for the build information: it can be the `*.class`, `*.jar`, or even the `*.war` files.

Scanning a build in ANT is achieved using the Java Build scanner executed as an ANT Java task.

{% code overflow="wrap" lineNumbers="true" %}

```java
<target name="sealights_scan" depends="compile,sealights_config">
    <java jar="${sealights.dir}/sl-build-scanner.jar" fork="true">
		<arg value="-scan"/>
		<arg value="-tokenfile"/>
		<arg value="${sealights.dir}/sltoken.txt"/>
		<arg value="-buildsessionidfile"/>
		<arg value="buildSessionId.txt"/>
		<arg value="-workspacepath"/>
		<arg value="${build}"/>
		<arg value="-r"/>
		<arg value="-fi"/>
		<arg value="*.class"/>
	</java>
</target>
```

{% endcode %}

* In order to add logs flags, you need to add the `<jvmarg>` values like below\
  `<jvmarg value="-Dsl.log.toConsole=true"/>`\
  `<jvmarg value="-Dsl.log.level=info"/>`

{% hint style="info" %}
See [#inlineextension-scanning-a-build](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/command-reference#inlineextension-scanning-a-build "mention") for full parameter details
{% endhint %}

## Running tests using JUnit <a href="#running-tests-using-junit" id="running-tests-using-junit"></a>

In order to capture code coverage information from tests run with JUnit, you need to run it with our test listener as a Java agent.

### JUnit 4.x <a href="#junit-4.x" id="junit-4.x"></a>

* The listener needs to be passed using the `jvmarg` attribute `-javaagent` parameter together with its required parameters.

{% code overflow="wrap" lineNumbers="true" %}

```java
<junit fork="yes">
  <jvmarg value="-javaagent:${sealights.dir}/sl-test-listener.jar"/>
  <jvmarg value="-Dsl.tokenFile=${sealights.dir}/sltoken.txt"/>
  <jvmarg value="-Dsl.buildSessionIdFile=buildSessionId.txt"/>
  <jvmarg value="-Dsl.testStage=Unit Tests"/>
</junit>
```

{% endcode %}

### JUnit 5.x <a href="#junit-5.x" id="junit-5.x"></a>

1. When tests are running in the same process, the listener needs to be passed using the `jvmarg` attribute `-javaagent` parameter with Sealights' Anonymous Execution mode deactivated.
2. When tests are running in a different process (via a fork), we need to add the `start` and `end` commands before and after tests execution

{% tabs %}
{% tab title="Same process (not forked)" %}

<pre class="language-java" data-overflow="wrap" data-line-numbers><code class="lang-java"><strong>&#x3C;junitlauncher>
</strong>	&#x3C;testclasses outputdir="build/test-report">
		&#x3C;jvmarg value="-javaagent:${sealights.dir}/sl-test-listener.jar"/>
		&#x3C;jvmarg value="-Dsl.tokenFile=${sealights.dir}/sltoken.txt"/>
		&#x3C;jvmarg value="-Dsl.buildSessionIdFile=buildSessionId.txt"/>
		&#x3C;jvmarg value="-Dsl.anonymousExecution=false"/>
		&#x3C;jvmarg value="-Dsl.testStage=Unit Tests"/>
	&#x3C;/testclasses>
	...
&#x3C;/junitlauncher>
</code></pre>

{% endtab %}

{% tab title="Different process (forked)" %}
{% code overflow="wrap" lineNumbers="true" %}

```java
<target name="test.junit.launcher" depends="compile">
	<java jar="${sealights.dir}/sl--test-listener.jar" fork="true">
		<arg value="start"/>
		<arg value="-tokenfile"/>
		<arg value="${sealights.dir}/sltoken.txt"/>
		<arg value="-buildsessionidfile"/>
		<arg value="buildSessionId.txt"/>
		<arg value="-testStage"/>
		<arg value="Unit Tests"/>
	</java>
	<junitlauncher haltOnFailure="true" printSummary="true">
		<classpath refid="test.classpath"/>
		<testclasses outputdir="build/test-report">
			<fork>
				<jvmarg value="-javaagent:${sealights.dir}/sl--test-listener.jar"/>
				<jvmarg value="-Dsl.tokenFile=${sealights.dir}/sltoken.txt"/>
				<jvmarg value="-Dsl.buildSessionIdFile=buildSessionId.txt"/>
				<jvmarg value="-Dsl.testStage=Unit Tests"/>
			</fork>
		</testclasses>
	</junitlauncher>
	<java jar="${sealights.dir}/sl--test-listener.jar" fork="true">
		<arg value="end"/>
		<arg value="-tokenfile"/>
		<arg value="${sealights.dir}/sltoken.txt"/>
		<arg value="-buildsessionidfile"/>
		<arg value="buildSessionId.txt"/>
	</java>
</target>
```

{% endcode %}
{% endtab %}
{% endtabs %}

{% hint style="info" %}
See [#installing-test-listener-as-java-agent](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/command-reference#installing-test-listener-as-java-agent "mention") for full parameter details
{% endhint %}

## Sample integration into an existing ANT project <a href="#sample-integration-into-an-existing-ant-project" id="sample-integration-into-an-existing-ant-project"></a>

In order to keep backward compatibility, you can use the `ant:if` condition to execute Sealights commands according to a boolean.\
In the sample below, you’ll be required to add `-Dsealights=true` to your ANT command in order to enable the agents.

{% hint style="info" %}
The sample below does not contain the command themselves for clarity. Please replace the `<echo>` lines with commands explained in previous sections.
{% endhint %}

{% code overflow="wrap" lineNumbers="true" %}

```java
<project name="sl-ant-sample" xmlns:if="ant:if">

    <target name="compile">
		<echo>Compiling the JAR</echo>
		<antcall if:true="${sealights}" target="sealights_scan" />
    </target>

	<target name="sealights_config">
		<echo>Sealights -- Create BSID</echo>
	</target>

	<target name="sealights_scan" depends="sealights_config">
		<echo>Sealights -- Scan artefacts</echo>
	</target>

	<target name="junit">
		<echo if:true="${sealights}">Sealights -- Add JVM arg</echo>
		<echo>Regular</echo>
  	</target>

</project>
```

{% endcode %}

Here is a comparison of executions with and without the `sealigths` parameter set to `true`.

<figure><img src="https://4057366433-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FAjqTCMRYvHhDgsdPLUnc%2Fuploads%2FFSE2Jmf5nWbYEXRPQbx1%2Fimage-20210614-190529.png?alt=media&#x26;token=29832c3d-0a8e-40fa-a3de-359fc19263a6" alt=""><figcaption></figcaption></figure>