/content/server/framework/atlassian-sdk/create-and-run-unit-tests.md
Markdown | 231 lines | 177 code | 54 blank | 0 comment | 0 complexity | 1ed72e51e54c6b48d6e8571dd5f3f9dd MD5 | raw file
Possible License(s): LGPL-2.0
- ---
- aliases:
- - /server/framework/atlassian-sdk/create-and-run-unit-tests-15335878.html
- - /server/framework/atlassian-sdk/create-and-run-unit-tests-15335878.md
- category: devguide
- confluence_id: 15335878
- dac_edit_link: https://developer.atlassian.com/pages/editpage.action?cjm=wozere&pageId=15335878
- dac_view_link: https://developer.atlassian.com/pages/viewpage.action?cjm=wozere&pageId=15335878
- date: '2017-12-08'
- guides: tutorials
- legacy_title: Create and Run Unit Tests
- platform: server
- product: atlassian-sdk
- subcategory: learning
- title: Create and run unit tests
- ---
- # Create and run unit tests
- This page explains how to create and run unit tests in a plugin. You should you have already worked through [Generate and Examine Skeleton Tests](/server/framework/atlassian-sdk/generate-and-examine-skeleton-tests). The Atlassian Plugin Framework requires that you use JUnit 4.10 or higher. By default, the SDK 4.1 (and higher) `atlas-` commands all generate a `pom.xml` file with a dependency on the appropriate JUnit version. If you are working with an older plugin, you should make sure to update JUnit `<version>` value to 4.10 before continuing.
- ## JUnit Quick Reminders
- You use JUnit to annotate test methods in your plugin. These annotations instruct and inform the JUnit framework how to interpret your test. The following table provides a short refresher of some common JUnit annotations:
- | Annotation Type | Description |
- |-----------------|------------------------------------------------------------------------------------------------------------|
- | `@After` | Release external resources allocated in the `@Before` method. |
- | `@AfterClass` | Release expensive external resources shared among tests. These are allocated in the `@BeforeClass` method. |
- | `@Before` | Create resources or prepares an environment before each `@Test`. |
- | `@BeforeClass` | Performs expensive environment setup or creates expensive resources shared among tests. |
- | `@Ignore` | Ignore the `@Test` method. |
- | `@Test` | Identifies a test method. |
- Recall that JUnit tests can run in any order. In fact, the order varies across different Java versions. So, remember to keep each unit test independent of another. If your tests are dependent, and they run in a different order than you expect, you may find it difficult to debug test failures. Test failure is another reason to keep your tests independent. If your tests are dependent, the failure of one can cause the remaining tests to fail.
- ## Step 1. Run the Generated MyComponentUnitTest
- When you created your plugin, the system generated a skeleton `MyPluginComponent.java` class. This class has a `getName()` method whose implementation relies on the Shared Access Layer (SAL) `com.atlassian.sal.api.ApplicationProperties` API. You'll find a unit test of this method in your `MyComponentUnitTest.java` class:
- ``` java
- @Test
- public void testMyName()
- {
- MyPluginComponent component = new MyPluginComponentImpl(null);
- assertEquals("names do not match!", "myComponent",component.getName());
- }
- ```
- When you next run your plugin with `atlas-run`, the command also runs your unit tests. Often, you only want to run your unit tests, you use the `atlas-unit-test` command to do this. The command executes only the `test` scope defined by the project `pom.xml` file. Try the `atlas-unit-test` command now:
- 1. Go to a command line.
- 2. Change to your plugin's top level `PLUGIN_HOME` directory.
- 3. Enter the `atlas-unit-test` command:
- ``` bash
- atlas-unit-test
- ```
- The command output should contain test output similar to the following:
- ``` bash
- ...
-
- [INFO] [surefire:test]
- [INFO] Surefire report directory: /Users/manthony/atlastutorials/testTutorial/target/surefire-reports
- -------------------------------------------------------
- T E S T S
- -------------------------------------------------------
- Running ut.com.example.plugins.tutorial.jira.testTutorial.MyComponentUnitTest
- Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.111 sec
- Results :
- Tests run: 1, Failures: 0, Errors: 0, Skipped: 0
- [INFO] ------------------------------------------------------------------------
- [INFO] BUILD SUCCESSFUL
- [INFO] ------------------------------------------------------------------------
- [INFO] Total time: 29 seconds
- [INFO] Finished at: Thu Nov 15 09:57:19 PST 2012
- [INFO] Final Memory: 69M/123M
- [INFO] ------------------------------------------------------------------------
- ```
- You can see that the generated unit test was successful.
- ## Step 2. Create a Failing Unit Test
- The build fails when one of your tests fails. Let's see how this work by adding a failling file. If you haven't already done so, start Eclipse and open the `testTutorial` you created.
- 1. Edit the `PLUGIN_HOME/src/main/java/com/atlassian/plugins/tutorials/jira/testTutorial/MyPluginComponent.java` file.
- 2. Add a new method to the file:
- ``` java
- int addNumbers(int x, int y);
- ```
- 3. Edit the `PLUGIN_HOME/src/main/java/com/atlassian/plugins/tutorials/jira/testTutorial/MyPluginComponentImpl.java` file.
- 4. Add the following code to the file:
- ``` java
- @Override
- public int addNumbers(int x, int y) {
- return x + y;
- }
- ```
- The plugin method adds two numbers together.
- 5. Save and close both files.
- 6. Locate the `PLUGIN_HOME/src/test/java/ut/com/atlassian/plugins/tutorials/jira/testTutorial/MyComponentUnitTest.java` file.
- 7. Edit the file and add the following unit test code:
- ``` java
- @Test
- public void testAdd()
- {
- MyPluginComponent component = new MyPluginComponentImpl(null);
- assertEquals("Result", 8, component.addNumbers(8, 8));
- }
- ```
- You should now have one passing test and a new one that should fail.
- 8. Close and save the file.
- 9. Go to a command line.
- 10. Make sure you are in at the top level `PLUGIN_HOME` directory for you plugin.
- 11. Enter the `atlas-unit-test` command.
- The failing test returns output similar to the following:
- ``` bash
- Failed tests: testAdd(ut.com.example.plugins.tutorial.jira.testTutorial.MyComponentUnitTest): Result expected:<8> but was:<16>
- ```
- With a failing test, the Maven build reports an error. If you were to run `atlas-run` at this point, it would fail also because you have a build error. If you have some time, try the `atlas-run` command.
- ## Step 3. Surefire Reports for Your Tests
- The Atlassian Plugin SDK uses the Maven Surefire Plugin during the `test` phase to run your tests. Running `atlas-unit-test` creates a `PLUGIN_HOME/target/test-classes` directory containing your compiled test. Surefire also creates a `PLUGIN_HOME/target/surefire` directory to hold temporary files during the test generation. After the test phase completes, Surefire generates a `PLUGIN_HOME/target/surefire-reports` directory.
- Take a moment and examine the Surefire report generated by your testing:
- 1. Change directory to `PLUGIN_HOME/target/surefire-reports` directory.
- 2. List the directory contents.
- You should see something similar to the following:
- ``` bash
- TEST-ut.com.example.plugins.tutorial.jira.testTutorial.MyComponentUnitTest.xml ut.com.example.plugins.tutorial.jira.testTutorial.MyComponentUnitTest.txt
- ```
- Both files are Surefire report files. Each time your tests you overwrite these files.
- 3. Take a minute and review the contents of each file.
- The XML report includes a set of environmental properties used in the test.
- The `@Ignore` annotation is useful if you want to skip a test you know is obsolete or you just aren't ready to use. Sometimes, during development, you may encounter tests that fail for other reasons. Remember the `atlas-` commands that start a host application with you plugin installed, also runs your tests. Failing test are inconvient if you just want to do `atlas-run` and see your test in a host application. Go ahead and ignore the failing test in your sample code:
- 1. Edit the `MyComponentUnitTest.java`.
- 2. Add an import for the JUnit @Ignore annotation.
- ``` bash
- import org.junit.Ignore;
- ```
- 3. Add the `@Ignore` annotation to the `testAdd()` method:
- ``` java
- @Ignore
- @Test
- public void testAdd()
- {
- MyPluginComponent component = new MyPluginComponentImpl(null);
- assertEquals("Result", 8, component.addNumbers(8, 8));
- }
- ```
- 4. Save and close the file.
- 5. Rerun your unit tests.
- You should see that only a single test is run, the first, the framework skips the other:
- ``` bash
- [INFO] [surefire:test]
- [INFO] Surefire report directory: /Users/manthony/atlastutorials/testTutorial/target/surefire-reports
- -------------------------------------------------------
- T E S T S
- -------------------------------------------------------
- Running ut.com.example.plugins.tutorial.jira.testTutorial.MyComponentUnitTest
- Tests run: 2, Failures: 0, Errors: 0, Skipped: 1, Time elapsed: 0.09 sec
- Results :
- Tests run: 2, Failures: 0, Errors: 0, Skipped: 1
- [INFO] ------------------------------------------------------------------------
- [INFO] BUILD SUCCESSFUL
- [INFO] ------------------------------------------------------------------------
- [INFO] Total time: 28 seconds
- [INFO] Finished at: Thu Nov 15 10:34:32 PST 2012
- [INFO] Final Memory: 69M/123M
- [INFO] ------------------------------------------------------------------------
- ```
- ## Step 4. Alternative Ways to Run or to Skip Tests
- Both Eclipse and IDEA allow you to run JUnit tests from within your IDE. If you are following along with this tutorial exactly, you should be using Eclipse. Go ahead and try this now:
- 1. Edit the `PLUGIN_HOME/src/test/java/ut/com/atlassian/plugins/tutorials/jira/testTutorial/MyComponentUnitTest.java` file.
- 2. Remove the `@Ignore` annotation you added in the previous procedure.
- 3. Save the file.
- 4. Select **Run As > JUnit** Test.
- You should see output similar to the following:
- <img src="/server/framework/atlassian-sdk/images/junit-fails.png" width="700" />
- Attempt an `atlas-run` now:
- 1. Go to the command line.
- 2. Change to your `PLUGIN_HOME` directory:
- 3. Enter the `atlas-run` command:
- ``` bash
- atlas-run
- ```
- Very quickly the `testAdd()` method fails, the build does not complete, and `atlas-run` exits without launching the host application.
- 4. Rather than editing your tests to fix the failure, which can be time consuming when you many tests, skip all tests from the command line by entering the following:
- ``` bash
- atlas-run -DskipTests=true
- ```
- It may have crossed your mind that skipping tests in general may be a good idea if you just want to run the host application and your project has a lot of tests!
- ## Next Steps
- In the next section, you learn about the [tools and processes for running traditional integration tests](/server/framework/atlassian-sdk/create-and-run-traditional-integration-tests).