Write and Run Tests

ScriptRunner makes easy things easier and allows experienced users to perform advanced tasks. You can do anything in a script that you could do in a plugin, usually without the overhead of understanding the host of software development tools and methodologies that a typical plugin developer would have to worry about.

If you’re using ScriptRunner extensively to write a lot of custom code or small amounts of custom code that heavily is relied on, you’re getting into the development platform portion of the product. Even if your formal job title or role is not in software development, that’s okay! You can write and run tests of your code to make sure it’s functioning.

Automated tests help complicated testing tasks, like:

• Detailed testing plans to make sure custom scripts work after upgrading linked instances of Jira and Confluence with repetitive tasks that need to be completed throughout the upgrade cycle

• Verification to make sure script works as you develop it, without having to click through several steps in the UI every time you make a change.

Not every ScriptRunner user needs to write tests, but when you feel that you need them, you should start writing them. For example, this need could be from doing repetitive work to tests scripts or fielding concerns from others about the reliability of custom scripts. Anything that makes you say, "I wish I had a quicker way to test this…​" is a good reason to start writing automated tests for your scripts.

An Aside for the Initiated Developer

Automated tests are integration tests, so they test your code within the context of a running Atlassian host application. The supported testing framework is Spock.

A unit test only tests your code, which typically means isolating your code by mocking any Atlassian managers and services. You could write a unit test, but it would be expensive to mock everything, and scripts are frequently simple enough that your logic isn’t complex enough to require testing.

The goal of automated testing is to make sure the script still works after you’ve made a change to the script or the environment where it runs.

If you’re building a script plugin with a host of custom classes that have deep business logic of their own, you may have different needs that require a unit test suite.

Writing and Running Tests

You can set up a test instance and/or local development environment where you can run your tests. You can get a development license to set up a test server where you can run a cloned instance of your Atlassian application.

ScriptRunner includes a testing library, Spock. Like ScriptRunner, it is from the Groovy ecosystem, and it makes automated tests more readable, maintainable, and approachable.

A basic Spock test looks like this:

groovy
import spock.lang.Specification
 
class MyVeryOwnScriptSpec extends Specification {
 
    def "test that my script does what I say it does"() {
        setup: "create any test data I need (projects, issues, etc.)"
 
        when: "I invoke run my script"
        //write code that makes your script run here
 
        then: "my script makes the changes I expect"
        true //Each line is an assertion
        1 == 1 //Anything that returns true will let the test pass
        "a" == "b" //Anything that returns false will cause the test to fail
    }
}

Fill in the lines beneath setup:, when:, and then: blocks with code that tests your script. The particulars of doing that will vary a bit based on what you’re testing (an event handler, a REST Endpoint, a Jira workflow function, etc.).

See the child pages of this page for some key particulars.

• Test Workflow Functions

• Test Script Fields

Once you’ve written your test, you can save it to one of your script roots and run it using the Running Tests task.

Test-Driven Workflow

When starting on a new feature, Adaptavist often uses a test-driven development workflow. This is the process:

1. Write a test for a desired outcome.

2. Run the test.

3. The test probably fails.

   This indicates that the feature isn’t working yet.

4. Implement the feature until the test passes.

5. Do any required code cleanup.

   1. Refactor.

   2. Make sure the test still passes.

6. Peer review.

7. Make suggested edits.

8. Test to make sure the code is running as expected.

Running Tests

There are two ways that you can run automated tests: through the Test Runner built-in script or via your IDE.

Test Runner Built-in Script

You can use the Test Runner built-in script to run Spock tests on the current Jira instance through ScriptRunner. The script creates custom test packages, and selects which tests to run from the checklist, simplifying the testing process.

1. From ScriptRunner navigate to Built-in Scripts > Test Runner.

   

2. Enter the name of the package(s) you want ScriptRunner to scan in Packages.

   Packages should follow the format com.yourcompany.scriptrunner.test, with all tests classes saved in the com/yourcompany/scriptrunner/test directory in your script root.

   The first time you open Test Runner, there is a pre-filled sample package com.acme.scriptrunner.test. This package contains sample tests. Run these tests to see an example of successful and failed tests. Running the pre-packaged tests creates a project with the key SRTESTPRJ, a workflow, and a workflow scheme.

   All these can be deleted, and they are recreated each time the test is run.

3. Select which tests to run from the Tests list.

   This list shows all available tests in the specified package.

4. Optionally, click Preview to see details of which tests will be executed.

5. Click Run to run the selected tests on the current instance.

   Do not run tests in a production instance.

6. The outcome of tests can be viewed under the Results tab.

Running From an IDE

You can run tests from your IDE. Adaptavist has only tested with Intellij IDEA and recommend it.

ScriptRunner includes a custom JUnit Platform Engine which executes the tests via REST in the running application (Jira, Confluence, Bitbucket etc). That engine will be automatically detected by JUnit Platform when executing tests so there isn't anything you need to do to make it work - simply extend spock.lang.Specification like you would do in any other Spock specification.

For example:

groovy
import spock.lang.Specification

class TestRunnerSampleSpec extends Specification {

    def "test something"() {
        expect:
        true
    }
}

IDEA Configuration

The IDE runs your test locally, which executes a REST call to the app. Therefore the IDE needs to know the address of your running application, so it can tell the app to run the tests. To do this, you can modify the default setting for JUnit tests:

1. Navigate to Run > Edit Configurations.

2. Open the Templates drop-down on the left navigation and then select JUnit.

3. For VM Options, add a property -Dbaseurl= pointing to the URL of the running application.

   You can omit this if you are running your application locally on port 8080, as in http://localhost:8080/jira.

4. Under Before Launch, delete the Build task using the minus button.

   It’s not necessary to rebuild the plugin after editing the tests because ScriptRunner will recompile the test if necessary.

5. Uncheck the Activate Tool Window box.

   It’s not useful to switch to the tool window because any failures will be shown in the main Log window.

Use the IDEA Test

• You can run the code by clicking the annotations in the margin, as shown below:

  

• The keyboard shortcut to run the code is to put the cursor in the test class name or method name, and then press Ctrl + Shift + F10 for Windows or Ctrl + Shift + R (on Mac OSX).