<commit_before>== Testing your addons

Forge offers several test harness to aid in writing tests for your addon. Each test harness has a specific role to play in testing your addon.

This chapter assumes knowledge of Arquillian, so you might find it easier to read the Arquillian tutorials at http://arquillian.org if you're not acquainted with it.

=== The Furnace test harness

The Furnace test harness offers the capability to deploy your and test addon to Furnace.

It is often included in your addon via the following dependencies:

[source,xml]
----
<dependency>
   <groupId>org.jboss.forge.furnace.test</groupId>
   <artifactId>furnace-test-harness</artifactId>
   <version>FURNACE_VERSION</version>
   <scope>test</scope>
</dependency>
<dependency>
   <groupId>org.jboss.forge.furnace.test</groupId>
   <artifactId>arquillian-furnace-classpath</artifactId>
   <version>FURNACE_VERSION</version>
   <scope>test</scope>
</dependency>
----

The `furnace-test-harness` artifact brings in the `junit` and `arquillian-junit-container` dependencies. You may recognize these two transitive dependencies if you're acquainted with Arquillian. They are crucial for writing and running JUnit based Arquillian tests.

You may also notice a need for an Arquillian container for the Furnace runtime. This is provided by the `arquillian-furnace-classpath` artifact. It brings in the Furnace runtime, support for making deployments to the Furnace runtime and provides APIs for deploying Forge addon dependencies.

With these two artifacts in your project, you will be able to test services offered by your addon.

TBD

You will not be able to write and execute end-to-end tests with the Furnace test harness. That responsibility is implemented in the Shell and UI test harnesses.<commit_msg>Copied text from README on testing addons.<commit_after>== Testing your addons

Forge offers several test harness to aid in writing tests for your addon. Each test harness has a specific role to play in testing your addon.

This chapter assumes knowledge of Arquillian, so you might find it easier to read the Arquillian tutorials at http://arquillian.org if you're not acquainted with it.

=== Setup the Furnace test harness in your project

The Furnace test harness offers the capability to deploy your and test addon to Furnace.

It is often included in your addon via the following dependencies:

[source,xml]
----
<dependency>
   <groupId>org.jboss.forge.furnace.test</groupId>
   <artifactId>furnace-test-harness</artifactId>
   <version>FURNACE_VERSION</version>
   <scope>test</scope>
</dependency>
<dependency>
   <groupId>org.jboss.forge.furnace.test</groupId>
   <artifactId>arquillian-furnace-classpath</artifactId>
   <version>FURNACE_VERSION</version>
   <scope>test</scope>
</dependency>
----

The `furnace-test-harness` artifact brings in the `junit` and `arquillian-junit-container` dependencies. You may recognize these two transitive dependencies if you're acquainted with Arquillian. They are crucial for writing and running JUnit based Arquillian tests.

You may also notice a need for an Arquillian container for the Furnace runtime. This is provided by the `arquillian-furnace-classpath` artifact. It brings in the Furnace runtime, support for making deployments to the Furnace runtime and provides APIs for deploying Forge addon dependencies.

With these two artifacts in your project, you will be able to test services offered by your addon.

==== Write your first test

Now, you'll need to create a test class with the following layout, using the standard JUnit test APIs:

[source,java]
----
package org.example;

import org.jboss.arquillian.container.test.api.Deployment;
import org.jboss.arquillian.junit.Arquillian;
import org.jboss.forge.arquillian.archive.ForgeArchive;
import org.jboss.shrinkwrap.api.ShrinkWrap;
import org.junit.Assert;
import org.junit.Test;
import org.junit.runner.RunWith;

@RunWith(Arquillian.class)
public class ExampleFurnaceTest {

   @Deployment
   public static ForgeArchive getDeployment() {
      ForgeArchive archive = ShrinkWrap.create(ForgeArchive.class);
      return archive;
   }

   @Test
   public void testSomething() throws Exception {
      Assert.fail("Not implemented");
   }
}
----

Then you'll need to add some configuration so that your addon will be deployed to the test environment. This is done
using the `@AddonDependency` annotation. You'll also need to add an addon dependency link from your test case
to your addon (otherwise the test case will not be able to use any of your addon's classes or services.)

[source,java]
----
@RunWith(Arquillian.class)
public class ExampleFurnaceTest {

   @Deployment
   @Dependencies({
       @AddonDependency(name = "org.example:example", version = "YOUR_VERSION")
   })
   public static ForgeArchive getDeployment() {
      ForgeArchive archive = ShrinkWrap.create(ForgeArchive.class)
         .addBeansXML()
         .addAsAddonDependencies(
            AddonDependencyEntry.create("org.example:example", "YOUR_VERSION"),
         );
      return archive;
   }

   @Test
   public void testSomething() throws Exception {
      Assert.fail("Not implemented");
   }
}
---- 

NOTE: The `@Dependencies` annotation is used to specify addons that must be deployed before the addon-under-test is deployed in Furnace. The `AddonDependencyEntry.create(...)` method is used to specify addons that the addon-under-test depends on.

Now that the test case deploys and depends on your addon, you may access services from it via injection:

[source,java]
----
@RunWith(Arquillian.class)
public class ExampleFurnaceTest {

   @Deployment
   @Dependencies({
       @AddonDependency(name = "org.example:example", version = "YOUR_VERSION")
   })
   public static ForgeArchive getDeployment() {
      ForgeArchive archive = ShrinkWrap.create(ForgeArchive.class)
         .addBeansXML()
         .addAsAddonDependencies(
            AddonDependencyEntry.create("org.example:example", "YOUR_VERSION"),
         );
      return archive;
   }
   
   @Inject
   private ExampleService service;

   @Test
   public void testSomething() throws Exception {
      Assert.assertNotNull(service);
      Assert.assertNotNull(service.doSomething());
   }
}
---- 

This is the basic premise of using the test-harness. For detailed examples, take a 
https://github.com/forge/core/tree/2.0/resources/tests/src/test/java/org/jboss/forge/addon/resource[look at some of the existing
Forge test cases] in our github repository.

NOTE: The `version` parameter in `@AddonDependency` and in the `AddonDependencyEntry.create(...)` method are optional. By not specifying them means that the test harness 
will attempt to find the version based on the tests' build descriptor (pom.xml). In this case, if the dependent addon is not present in the tests' build descriptor, the test execution should fail.

You will not be able to write and execute end-to-end tests with the Furnace test harness. That responsibility is implemented in the Shell and UI test harnesses.
{'fraction_non_alphanumeric': 0.07957295373665481, 'fraction_numerical': 0.00028469750889679714, 'mean_word_length': 4.18141592920354, 'pattern_counts': {'":': 0, '<': 43, '<?xml version=': 0, '>': 43, 'https://': 1, 'lorem ipsum': 0, 'www.': 0, 'xml': 3}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3382583', 'n_tokens_mistral': 2072, 'n_tokens_neox': 1911, 'n_words': 769}