1. Главная
  2. ИЗУЧЕНИЕ
  3. Учебники и руководства
  4. Написание интеграционных тестов для вашей надстройки JIRA

Написание интеграционных тестов для вашей надстройки JIRA

Уровень опыта: средний

Наши учебники классифицируются как «новичок», «средний» и «продвинутый». Этот уровень находится на «среднем» уровне. Если вы еще никогда не разрабатывали плагин, вы можете найти это немного сложнее.

Обзор

В этом учебном пособии показано, как создавать интеграционные тесты для плагина. Этот учебник демонстрирует, как писать такие тесты для обоих элементов пользовательского интерфейса, предоставляемых самим плагином, а также для хост-приложения.

Для этого вы создадите плагин JIRA. Как и все плагины, ваш плагин будет состоять из следующих компонентов:

  • Классы Java, инкапсулирующие логику плагина
  • Ресурсы для отображения пользовательского интерфейса плагина
  • Дескриптор плагина для включения модуля плагина в JIRA.

Все эти компоненты будут содержаться в одном JAR-файле. Каждый компонент обсуждается далее в примерах ниже.

Существуют различные определения, доступные для тестирования интеграции. Для целей этого руководства тестирование интеграции определяется как запуск набора автоматических тестов против веб-интерфейса вашего плагина, используя HTTP-запросы и ответы, чтобы утверждать, что веб-интерфейс демонстрирует правильное поведение.

Источник плагина

Мы рекомендуем вам проработать этот учебник. Если вы хотите пропустить или проверить свою работу, когда вы закончите, вы можете найти исходный код плагина на Atlassian Bitbucket. Bitbucket служит публичному репозиторию Git, содержащему код учебника. Чтобы клонировать репозиторий, выполните следующую команду:


$ git clone https://atlassian_tutorial@bitbucket.org/atlassian_tutorial/jira-integration-tests-plugin.git

Кроме того, вы можете скачать исходный код с помощью страницы загрузки здесь: bitbucket.org/atlassian_tutorial/jira-integration-tests-plugin

Шаг 1. Создайте проект плагина

Используйте соответствующую команду atlas-create-application-plugin для создания своего плагина. Например, atlas-create-jira-plugin или atlas-create-confluence-plugin.

Когда вы создаете плагин с использованием вышеуказанного SDK, вам будет предложено указать некоторую информацию для идентификации вашего плагина. Введите следующую информацию:

  • group-id: com.atlassian.plugins.tutorial
  • artifact-id: jira-integration-tests-tutorial
  • version: 1.0
  • package: com.atlassian.plugins.tutorial

Шаг 2. Добавление метаданных плагина к POM

Теперь вам нужно отредактировать свой POM (файл определения объектной модели проекта), чтобы добавить некоторые метаданные о вашем плагине и вашей компании или организации.

  1. Измените файл pom.xml в корневой папке вашего плагина.
  2. Добавьте название вашей компании или организации и ваш сайт в элемент <organization>:

<organization>
<name>Example Company</name>
<url>http://www.example.com/</url>
</organization>
  1. Обновите элемент <description>:

<description>This plugin demonstrates how to write integration tests for a JIRA plugin.</description>
  1. Сохраните файл.

Шаг 3. Зарегистрируйте модуль плагина в дескрипторе плагина

Теперь вы добавите необходимые модули плагинов в свой дескриптор плагина в src / main / resources / atlassian-plugin.xml. Дескриптор плагина представляет собой XML-файл, который идентифицирует плагин для JIRA и определяет функциональные возможности, которые требует плагин.

Вот базовый дескриптор плагина:


<atlassian-plugin key="${project.groupId}.${project.artifactId}" name="${project.artifactId}" plugins-version="2">
<plugin-info>
<description>${project.description}</description>
<version>${project.version}</version>
<vendor name="${project.organization.name}" url="${project.organization.url}" />
</plugin-info>
</atlassian-plugin>

Обратите внимание, что часть информации из POM передается в дескриптор плагина с использованием имен переменных, таких как $ {project.artifactId}.

Вам понадобится следующий модуль плагина:


<webwork1 key="showcurrentuser" name="Show Current Users Project Permissions" class="java.lang.Object">
    <actions>
        <action name="com.atlassian.plugins.tutorial.ShowUsersProjectPermissionAction"
                alias="ShowUsersProjectPermissionAction">
            <view name="success">/templates/showprojects.vm</view>
            <view name="error">/templates/showprojects.vm</view>
        </action>
    </actions>
</webwork1>

Вышеприведенный фрагмент кода вводит действие веб-сайта в этот плагин. Это не является обязательным требованием для написания интеграционных тестов, но оно добавляет хороший пример для написания тестов интеграции.

Теперь вы готовы перейти к написанию кода, чтобы сделать ваш плагин чем-то.

Шаг 4. Запишите классы Java

В этом плагине вы захотите написать интеграционные тесты для некоторых точек плагинов, определенных вашим плагином.

Чтобы сделать это, вы напишете действие веб-поиска, которое просто отобразит проекты, в которых у текущего пользователя, имеющего доступ, есть разрешение, предоставленное в качестве параметра. Так, например, пользователь сможет показать все проекты, в которых у него(или ее) есть разрешение Create Issue на создание задачи. Действие веб-сайта также проведет некоторые проверки ошибок, чтобы гарантировать, что только зарегистрированные пользователи могут запросить(query) эту информацию и что предоставленное разрешение как параметр для действия является допустимым разрешением JIRA.

Сначала нам нужно сконструировать действие веб-сайта с помощью JIRA PermissionManager, который будет использоваться для проверки того, на какие проекты у пользователя есть заданное разрешение:


    public ShowUsersProjectPermissionAction(final PermissionManager permissionManager)
    {
        this.permissionManager = permissionManager;
    }

Когда пользователь отправляет запрос (request) на это действие, нам нужно выполнить некоторую проверку(валидацию):


    @Override
    protected void doValidation()
    {
        final User user = getRemoteUser();
        //check if a user is logged in, otherwise return with an appropriate error message
        if (user == null)
        {
            addErrorMessage("Please login to view the current user's projects for a permission.");
        }
        final int permissionType = Permissions.getType(permission);
        //then check if the permission provided as a parameter is a valid JIRA permission
        if (permissionType == -1)
        {
            addErrorMessage("Invalid permission specified.  Permission '" + permission + "' is unknown!");
        }
    }

Если проверка(валидация) прошла, метод doExecute () вызывается для получения информации, которой мы пользуемся:


    @Override
    protected String doExecute() throws Exception
    {
        final User user = getRemoteUser();
        final int permissionType = Permissions.getType(permission);

        //retrieve all the projects that the current user has the given permission type in.
        projects = permissionManager.getProjectObjects(permissionType, user);
        return SUCCESS;
    }

Наконец, для всех действий веб-сайта требуется соответствующее представление:


<html>
<body>
    #if($action.hasAnyErrors())
        <ul>
            #foreach($error in $action.getErrorMessages())
                <li>$error</li>
            #end
        </ul>
    #else
        <div>The user $action.remoteUser.name has the '$action.permission' permission in the following projects:</div>
        <ul id="projects-list">
            #foreach($project in $action.projects)
            <li>$project.name ($project.key)</li>
            #end
        </ul>
    #end
</body>
</html>

Шаг 5. Создание, установка и запуск плагина

Выполните следующие шаги для создания и установки своего плагина, так чтобы вы могли проверить свой код. Если вы еще не запустили приложение, запустите его сейчас:

  • Откройте командное окно и перейдите в корневую папку плагина (где находится pom.xml).
  • Запустите atlas-run (или atlas-debug, если вы захотите запустить отладчик в своей среде IDE).

С этого момента вы можете использовать QuickReload для переустановки своего плагина за сценой, когда работаете, просто перестроив свой плагин.

FastDev и атлас-cli устарели. Вместо этого используйте автоматическую переустановку плагинов с помощью QuickReload.

Чтобы запустить переустановку вашего плагина:

  1. Внесите изменения в модуль плагина.
  2. Откройте панель инструментов разработчика.

РИСУНОК

  1. Нажмите значок FastDev.

РИСУНОК

Система перестраивает и перезагружает ваш плагин:

РИСУНОК

Используйте живую перезагрузку для просмотра обновлений в реальном времени для шаблонов и других ресурсов:

  1. Откройте панель инструментов разработчика.
  2. Нажмите значок живой перезагрузки.Значок начинает вращаться, показывая, что он включен.
  3. Отредактируйте ресурсы проекта.
  4. Сохраните изменения:Вернувшись в приложение хоста, ваш плагин отображает все видимые вами изменения пользователя.

Вернитесь в браузер. Обновленный плагин был установлен в приложение, и вы можете проверить свои изменения.

Полные инструкции приведены в руководстве SDK.

Вы должны иметь возможность посетить localhost: 2990 / jira / secure / ShowUsersProjectPermissionAction.jspa? Permission = create, чтобы просмотреть список всех проектов, в которых у вас есть разрешение на создание задачи(Create Issue). Это может потребовать от вас сначала создать некоторые проекты.

Шаг 6. Запись и интеграция тестов

В настоящее время существует новый, объектно-ориентированный способ написания интеграционных тестов. Этот раздел предназначен для

рекомендационных и  унаследованных тестов интеграции. Советуем вам написать интеграционные тесты с помощью Page Objects.

Поздравляем! Вы добрались до мясистой части этого урока. Мы сосредоточимся только на тестах интеграции, поскольку на самом деле нет ничего, чтобы тестировать модуль.

Прежде чем перейти к написанию интеграционного теста, расскажем немного о том, как работают интеграционные тесты в JIRA. Интеграционные тесты JIRA управляются jWebUnit (хотя довольно древняя версия: 1.2). Цель jWebUnit состоит в том, чтобы имитировать браузер, делать HTTP-запросы к вашему веб-приложению и делать утверждения о состоянии, возвращенном в ответах вашего приложения. Он предоставляет ряд встроенных методов, чтобы сделать это проще, например clickLink («linkid») и assertTextPresent («Пример текста»).

JIRA построила фреймворк тестирования интеграции поверх этого, чтобы упростить определенные действия в JIRA. Исторически, интеграционные тесты были бы написаны путем расширения JiraWebTest, который предоставит все эти методы полезности вашему тесту интеграции. Это теперь заменено новой платформой для тестирования интеграции JIRA, которая обеспечивает гораздо лучшую документацию и является более гибкой и расширяемой. Пожалуйста, прочитайте документы API фреймворка для получения более подробной информации о том, что возможно (убедитесь, что вы проверяете все интерфейсы в основном пакете, поскольку они содержат все полезные полезные методы, доступные вам).

Прежде чем мы начнем писать интеграционный тест, вам нужно создать файл localtest.properties в папке src / test / resources:


jira.protocol = http
jira.host = localhost
jira.port = 2990
jira.context = /jira
jira.edition = all

jira.xml.data.location = src/test/xml

Интеграционный тестовый фреймворк JIRA использует этот файл, чтобы выяснить, под каким URL работает ваш экземпляр JIRA, и где найти файлы резервной копии XML, которые ваши тесты могут импортировать для настройки тестовых данных. На каком-то этапе в ближайшем будущем этот файл будет сгенерирован автоматически.

После того, как у вас есть файл localtest.properties, вы можете начать писать свой тестовый пример интеграции в src / test / java / it:


public class ShowUsersProjectPermissionTest extends FuncTestCase

Чтобы написать интеграционный тест, используя фреймворк тестирования интеграции JIRA, ваш тестовый класс должен расширить FuncTestCase. Этот класс предоставляет ряд помощников, таких как administration, text и navigation, чтобы упростить интеграционное тестирование. Обратите внимание, что тесты, не находящиеся в этом каталоге it, позже рассматриваются как модульные тесты с помощью команды atlas-integration-test, что означает, что JIRA не будет автоматически запущена, и все «модульные тесты» потерпят неудачу.

Прежде чем вы сможете начать тестирование, нам нужно настроить JIRA с некоторыми данными, которые мы можем использовать для тестирования. Это лучше всего сделать, импортировав резервную копию XML до запуска теста:


@Before
public void setUpTest()
{
    //restore some test data.  This particular export contains 2 projects and one issue.
    administration.restoreData("TestShowUsersProjectPermission.xml");
}

Этот метод использует помощник administration для восстановления резервной копии TestShowUsersProjectPermission.xml в JIRA.

Хотя вы можете использовать вспомогательные классы, предоставляемые FuncTestCase для создания тестовых данных, это обычно не рекомендуется. Например, создание большого количества проблем таким образом может быть очень медленным. Лучше сначала  вручную создать ваши тестовые данные, которые затем можно возвратить в XML и импортировать в ваш тест.

Теперь у нас есть настройка JIRA с некоторыми данными, и мы можем начать писать наш первый тест. Давайте проверим действие веб-сайта, которое мы написали ранее:


/**
 * This particular test checks that the webwork action included in this plugin provides the correct information and
 * error messages.
 */
@Test
public void testUsersProjectPermissions()
{
    navigation.logout();
    navigation.gotoPage("/secure/ShowUsersProjectPermissionAction.jspa?permission=create");
    text.assertTextPresent(new WebPageLocator(tester),
            "Please login to view the current user's projects for a permission.");
    navigation.login("admin", "admin");
    navigation.gotoPage("/secure/ShowUsersProjectPermissionAction.jspa?permission=invalidpermission");
    text.assertTextPresent(new WebPageLocator(tester),
            "Invalid permission specified.  Permission 'invalidpermission' is unknown!");
    navigation.gotoPage("/secure/ShowUsersProjectPermissionAction.jspa?permission=create");
    text.assertTextPresent(new WebPageLocator(tester), "The user admin has the 'create' permission in the following projects");
    text.assertTextSequence(new IdLocator(tester, "projects-list"), "Homosapien (HSP)", "Monkey (MKY)");
}

Этот конкретный тест перемещается к нашему действию веб-сайта, перейдя к определенному URL-адресу и утверждает, что скорректированный текст был возвращен. Этот тест не использует jWebUnit напрямую, но вместо этого использует помощники, предоставляемые фреймвоком тестирования интеграции JIRA. Одним из наиболее полезных примеров является шаблон text.assertTextPresent (SomeLocator). Довольно часто веб-страница будет содержать один и тот же текст в нескольких разных местах на веб-странице (например, имя зарегистрированного пользователя может отображаться в заголовке страницы, а также в поле репортера задачи), и необходимо, чтобы только запускать утверждение в определенной части страницы. Локаторы - являются способом ограничения части страницы, на которой выполняется утверждение. Это одна из самых мощных частей платформы тестирования интеграции, и мы настоятельно рекомендуем ознакомиться с различными типами локаторов, доступных вам.

Наконец, давайте продемонстрируем несколько более продвинутых способов написать тест интеграции:


/**
 * This test does not test anything from this plugin.  It simply uses the func test framework to perform a number
 * of actions and assertions in JIRA for the purposes of this tutorial.
 * It shows how to:
 * <ul>
 * <li>Create a user</li>
 * <li>Create an issue</li>
 * <li>Add a comment to an issue</li>
 * <li>Carry out various assertions</li>
 * </ul>
 */
@Test
public void testJiraActions()
{
    /* first lets create a user */
    administration.usersAndGroups().addUser("fred", "password", "Fred Flintstone", "fred@example.com");
    /* check the user exists.  The previous action would have done this already, but lets check anyway */
    navigation.gotoAdminSection("user_browser");
    //click a link with id fred using jWebUnit
    tester.clickLink("fred");
    text.assertTextSequence(new WebPageLocator(tester),
            "Username:", "fred", "Full Name:", "Fred Flintstone", "Email:", "fred@example.com");
    //also try logging in as that user
    navigation.logout();
    navigation.login("fred", "password");
    navigation.logout();
    navigation.login("admin", "admin");
    /* Lets create a new issue */
    final String issueKey = navigation.issue().createIssue("Homosapien", "Bug", "This is a first bug");
    navigation.issue().viewIssue(issueKey);
    //various ways for asserting stuff.
    // 1. Using text assertions from JIRA's integration test framework using Locators
    //    Locators are awesome.  Very flexible ways to Locate particular parts of your webpage, and very easy to write
    //    yourself
    text.assertTextPresent(new TableLocator(tester, "issue_header_summary"), "This is a first bug");
    // 2. Using jWebUnit directly
    tester.assertTextInTable("issue_header_summary", "This is a first bug");
    // 3. Or if you're really desperate by String comparison using the HTML source returned in the response.
    final String htmlSource = tester.getDialog().getResponseText();
    assertTrue(htmlSource.contains("This is a first bug"));
    // 4. Asserting some text is not present
    text.assertTextNotPresent(new WebPageLocator(tester), "Fred Flintstone");
    /* Lets add a comment to an issue and check it was created properly */
    navigation.issue().addComment(issueKey, "I'm not sure this is the bug you're looking for.", null);
    navigation.issue().viewIssue(issueKey);
    text.assertTextPresent(new IdLocator(tester, "issue_actions_container"),
            "I'm not sure this is the bug you're looking for.");
}

Этот тест демонстрирует некоторые более продвинутые вещи, которые возможны с фреймвоком тестирования интеграции JIRA. Строка 82 также демонстрирует, как использовать jWebUnit непосредственно через переменную tester, если это когда-либо понадобится.

Для запуска этого теста вы можете просто запустить atlas-integration-test из командной строки. Это создаст ваш плагин, запустит JIRA и запустит все тесты. Чтобы запускать отдельные тесты, вы также можете запустить JIRA с помощью atlas-run и выполнить свой тест из своей IDE. В Intellij вы можете просто щелкнуть правой кнопкой мыши по методу и нажать «Выполнить» <TESTNAME> »:

РИСУНОК

Если есть какие-либо сбои в тестировании, сборка завершится неудачно:


Tests run: 2, Failures: 1, Errors: 0, Skipped: 0

[INFO] ------------------------------------------------------------------------
[ERROR] BUILD ERROR
[INFO] ------------------------------------------------------------------------
[INFO] Unable to execute mojo

Embedded error: There are test failures.

Please refer to /Users/andreask/projects/atlassian/jira-integration-tests-tutorial/target/jira/tomcat6x/surefire-reports for the individual test results.

Каталог, указанный в журнале сборки, будет содержать текстовый файл для каждого тестового класса в вашем тестовом пакете интеграции с более подробной информацией о том, что пошло не так:


-------------------------------------------------------------------------------
Test set: it.ShowUsersProjectPermissionTest
-------------------------------------------------------------------------------
Tests run: 2, Failures: 1, Errors: 0, Skipped: 0, Time elapsed: 72.129 sec <<< FAILURE!
testUsersProjectPermissions(it.ShowUsersProjectPermissionTest)  Time elapsed: 40.25 sec  <<< FAILURE!
junit.framework.AssertionFailedError: The text 'The user admin h the 'create' permission in the following projects' could not be found via locator WebPageLocator : 1 node(s) - 'Welcome - Your Company JIRA var conte...'
        at junit.framework.Assert.fail(Assert.java:47)
        at com.atlassian.jira.functest.framework.assertions.TextAssertionsImpl.assertTextPresentImpl(TextAssertionsImpl.java:71)
        at com.atlassian.jira.functest.framework.assertions.TextAssertionsImpl.assertTextPresent(TextAssertionsImpl.java:39)
        at it.ShowUsersProjectPermissionTest.testUsersProjectPermissions(ShowUsersProjectPermissionTest.java:39)
...

В этом случае я ошибся с текстом «Администратор пользователей h «создать »разрешение в следующих проектах» в строке 39 теста ShowUsersProjectPermissionTest.

 

Поздравляю, вот и все

Теперь вы можете написать интеграционные тесты для JIRA.

 О, и не забывайте, что есть шоколад!

ПОХОЖИЕ ТЕМЫ

  • Ресурсы тестирования и обсуждения плагинов
  • Написание интеграционных тестов с использованием объектов Page
  • Интеллектуальное тестирование с TestKit

 

По материалам Atlassian JIRA  Server Developer Writing integration tests for your JIRA add-on