.. _gsauto_ug_annotations:

Аннотации
=========

В главе :ref:`gsauto_ug_selection` описывалось выполнение 
операций и JEXL-скриптов.

При интеграции библиотеки с JUnit по схеме :ref:`с использованием расширения <junit-init-extension>`, 
доступны удобные способы выполнения этих действий в разных фазах выполнения тестов.

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

Аннотации объявлены в пакете `gs-automation-environments` и 
интегрируются с JUnit в пакете `gs-automation-junit`.

Детали работы с этими аннотациями описаны в документации API библиотеки.
Здесь приводятся основные примеры их использования.

.. seealso::
   - Руководство пользователя: :ref:`gsauto_ug_selection`
   - Руководство пользователя: :ref:`gsauto_ug_junit`
   - Руководство пользователя: :ref:`gsauto_ug_artifacts`
   - Справочник API: :doc:`API интеграции с JUnit <../../javadoc-junit/packages>`

Аннотации допустимо применять к методам, аннотированным ``@BeforeAll``, ``@BeforeEach``, ``@AfterAll`` и ``@AfterEach``.

.. note::

   1. Для методов, аннотированных ``@Before``, сначала выполняется метод, затем операция/скрипт.
   2. Для методов, аннотированных ``@After``, сначала выполняется операция/скрипт, затем метод.
   3. К методам можно применять несколько аннотаций ``@Oper`` и ``@Jexl``.

Аннотация @Oper
---------------

Аннотация :java:type:`@Oper<ru.bitec.gs.automation.environment.Oper>` вызывает операцию в контексте выборки.

Пример использования:

.. code-block:: java
   :caption: Применение аннотации @Oper

   import org.junit.jupiter.api.*;
   import ru.bitec.gs.automation.junit.GsAutomationJUnitEnvironment;
   import ru.bitec.gs.automation.environment.*;

   public class OperAnnotationTest extends GsAutomationJUnitEnvironment {
      private Form form;

      @BeforeAll
      @Oper(name = "tb_beforeAll", form = "gtk-ru.bitec.app.gs3.qa.gsauto.Gs3_QaGsAuto_Masterdata_Grid#List")
      public void beforeAll() {
         application.mainForm().mainMenu().item("mm_Selection", "mm_gsauto_masterdata").click();
         form = application.waitMdiForm("gtk-ru.bitec.app.gs3.qa.gsauto.Gs3_QaGsAuto_Masterdata_Grid", "List");
      }

      @AfterAll
      @Oper(name = "tb_afterAll", form = "gtk-ru.bitec.app.gs3.qa.gsauto.Gs3_QaGsAuto_Masterdata_Grid#List")
      public void afterAll() {
         form.mainSelection().layout().frame().toolbar().button(StandardOperations.CLOSE_FORM_CANCEL).click();
         form.waitClosing();
      }
   }


Аннотация @Jexl
---------------

Аннотация :java:type:`@Jexl<ru.bitec.gs.automation.environment.Jexl>` похожа на
аннотацию ``@Oper``, но предназначена для выполнения JEXL-скриптов.

Пример использования:

.. code-block:: java
   :caption: Применение аннотации @Jexl

   import org.junit.jupiter.api.*;
   import ru.bitec.gs.automation.junit.GsAutomationJUnitEnvironment;
   import ru.bitec.gs.automation.environment.*;

   public class JexlAnnotationTest extends GsAutomationJUnitEnvironment {
      private Form form;

      @BeforeAll
      @Jexl(script = "selection.locate(asScala({'id': 42L}))", form = "gtk-ru.bitec.app.gs3.qa.gsauto.Gs3_QaGsAuto_Masterdata_Grid#List")
      public void beforeAll() {
         application.mainForm().mainMenu().item("mm_Selection", "mm_gsauto_masterdata").click();
         form = application.waitMdiForm("gtk-ru.bitec.app.gs3.qa.gsauto.Gs3_QaGsAuto_Masterdata_Grid", "List");
      }

      @AfterAll
      @Jexl(script = "selection.locate(asScala({'id': 1L}))", form = "gtk-ru.bitec.app.gs3.qa.gsauto.Gs3_QaGsAuto_Masterdata_Grid#List")
      public void afterAll() {
         form.mainSelection().layout().frame().toolbar().button(StandardOperations.CLOSE_FORM_CANCEL).click();
         form.waitClosing();
      }
   }

Допустимо указывать либо код JEXL-скрипта, либо имя файла, содержащего код JEXL-скрипта.

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