baangt/docs/simpleExample.rst

Jump-start into worry free production deployments
=================================================

You can try baangt right away and see how it works. It'll take less than 5 minutes.

Prerequisits
^^^^^^^^^^^^^

* Chrome installed
* Python3 installed
* ``baangt`` installed (either via PIP or from the GIT-Repository at https://gogs.earthsquad.global/athos/baangt)

If you prefer running ``baangt`` inside Docker, use the Dockerfile from https://gogs.earthsquad.global/athos/baangt-Docker.
After downloading the repository, enter ``make build`` and then ``make run`` in the command line.
Once Docker is up, use SVN://localhost:5902 to connect. All features are exactly like you'd install everything on your local machine.

Let's dive right into it
^^^^^^^^^^^^^^^^^^^^^^^^^

* Start baangt interactive UI by typing `python baangtIA.py`
* In the dropdown "Testrun" chose "SimpleTheInternet.xlsx" and click on "Execute TestRun"
* What's happening here is pretty similar to a real world test case:
    * Browser (in this case Firefox) starts up
    * Navigate to a certain web page
    * click on a link
    * navigate back
    * click on other link
    * click on several elements of the page (e.g. buttons)
    * write a report with summary and details about the test case. You'll find the report in the root directory of baangt, unless you stated otherwise.


Extend the Script:
------------------

For this to work we recommend an XPATH or CSS-plugin for your browser.

Follow these steps to modify the behaviour of the test script:

* Open "SimpleTheInternet.xlsx" from the baangt root directory in Excel or OpenOffice
* In your browser with activated XPATH or CSS-Plugin head over to http://the-internet.com
* Choose one of the links, that you want to play around with and find the XPATH or CSS from your tool.
* Copy and paste this ID in the last line of the XLSX in column C ("Locator").
    * Column A ("Activity") should be "CLICK"
    * Column B ("LocatorType") will be either XPATH or CSS depending on your tool
* Save the XLSX
* Execute the testrun "SimpleTheInternet.xlsx" in ``baangt`` again.
* Sit back and enjoy your victory!

.. hint::

    If you want to be able to watch your browser executing each step, we recommend you set the parameter ``slowExecution`` with value ``True`` in Globals and re-run the test

.. hint ::
    If you want the browser window to stay open on errors and/or after execution, you can use parameter ``dontCloseBrowser`` with value ``True``
    in global settings and run the test again. The browser will stop on errors or when the test run execution stopped.

A bit further
-------------

Go ahead and try it out with your personal real-world example of a web-page, web-app or SPA, which you would like to have
reproducable regression tests for.

Of course you could basically follow the steps above, but depending on the length and complexity of the execution, you'll
definitely enjoy having more tools in your toolbox:

Recording a test case with Katalon Recorder
-------------------------------------------

Katalon Recorder is a free browser Add-on for Chrome and Firefox. Installation is simple, just google
``Katalon plugin <your-browser>`` and install the plugin. After installation of the Katalon recorder follow these steps:

* Start the plugin
* Hit the "record"-Button
* Execute the activities you want it to record. Usually following these steps:
    * Open a Webpage
    * Login (optional)
    * Navigate to some sub-page
    * Click buttons
    * Enter values
    * Download documents (optional)

* Stop recording

  .. hint::

     You might want to execute the test case from within Katalon Recorder to make sure everything was recorded properly.

* Hit the export-Button of the recorder, chose format ``other``
* Click "Export to Clipboard"
* Switch over to ``baangt`` and press the button "Import KatalonRecorder"
    * The contents from the clipboard should be imported already and translation to ``baangt`` should be completed. If the clipboard was not inserted automatically, click on the button "Import Clipboard" and please drop a ticket stating your operating system incl. version and which browser you used for recording in Katalon recorder.
* Press "Save" and choose where you want to store the resulting XLSX-File

**That's it. You just created you first regression test case including all parameters for it.**

If you're wondering which parameters these are, and how you can influence them, fear not! Open the Testcase-XLSX from
the last step above, click on the "data"-Tab and start to enter values and lines as you please.

You can always re-run Baangt after saving your Testrun-XLSX and see your progress.

.. hint::

    If you want to be able to watch your browser executing each step, set the parameter ``slowExecution`` with value ``True`` in Globals and re-run the test

Tweaking the result
^^^^^^^^^^^^^^^^^^^

You managed to have a working recording. Congratulations! Let's learn a bit more about the structure of the created XLSX

.. list-table:: Fields in Tab ``TestStepExecution``
   :widths: 25 75
   :header-rows: 1

   * - Column Name
     - Description
   * - ``Activtity``
     - Sets the activity of this TestStep. Activities are described in more details in next chapter
   * - ``LocatorType``
     - Most of the activities need a locator. We are big fans of XPATH as locatorType, due to speed and ease of use. Sooner
       or later you'll anyway end up needing XPATH, so why not use it always when there's no downside? If you prefer
       writing CSS-Paths then use value ``CSS`` for the locator. And if you are lucky enough to have unique IDs in your
       page simply use ``ID``.
   * - ``Locator``
     - The locator is the specification on which element ``Activity`` should happen. As in the value fields, you may
       use variable replacement here too, in order to replace Locators with values from the data file. For instance the
       following would work fine:
       ``//*[@id($(CUSTOMERNUMBER))]`` - this would create an XPATH-Statement where $(CUSTOMERNUMBER) is replaced by the
       actual value of the current test record.
   * - ``Value``
     - For instance activity ``SetText`` requires a value (The text to send to a Web-element). You may use fixed values
       (which will rarely happen) or values from your test data source, in the simple cases the sheet ``Data`` .
       The column names in the sheet ``data`` can be used as variable names (e.g. if you created a column "Quantity" in
       your data tab, you can use ``$(Quantity)`` in the field value.
   * - ``Comparison`` and ``Value2``
     - For some activities (e.g. IF) you not only need the Value-Field but also a comparison operator and a
       second field or value to compare to. Values for ``comparison`` are ``eq`` and ``=``. The field ``value2``
       follows the same logic as ``value``.
   * - ``Timeout``
     - Sometimes you might to overwrite the default timeout settings of ``baangt``. Here's your chance. Values in seconds,
       decimals are OK (``0.5`` is a valid value, so is ``90``).
   * - ``Optional``
     - Usually when ``baangt`` tries to execute an activity and can't (after timeout), it will throw an exception,
       report in the Logs and stop the current test case. If you set ``optional`` to ``True`` or ``X``, ``baangt``
       will continue execution of the test case, even if the activity wasn't possible.
   * - ``Release``
     - Often you'll face situations, where you want to run a test case in several stages (e.g. DEV, Pre-Quality, Quality,
       Migration, Pre-Production, etc.) and the software version on each stage is different. A test case, that works on
       Pre-Production will not pass on Dev-System as Dev is already further developed. If you change the test case to work
       on Dev-System and you need to test a Hotfix deployment on Pre-Production, what will you do? In other test solutions
       you would "simply" copy your test case, have one version for DEV, one for Pre-Production. Do that with hundreds of
       different test cases and watch yourself drown in chaos. OR you could use ``baangt`` where this problem is solved.
       Software moves through the stages of your system landscape as it evolves. Use this field to conditionally execute
       different "branches" of your test cases, depending on the version on the current stage. ``Release`` can be any
       string value. You can add "> " "< " and "= " as the first 2 characters to signal to ``baangt`` to only execute
       the step when current release is greater than, lower than or exactly equal to the value afterwards, for instance

       ::

         > 2019.05

       will run the line only, if the Version is ``2019.05a`` or ``2019.06``. We are aware, that your version numbers might
       follow different nomenclature, so we made it very easy to subclass the corresponding logic.

More details on Activities
--------------------------

.. list-table:: Details of activities
   :widths: 25 75
   :header-rows: 1

   * - Activity
     - Description
   * - GoToURL
     - Navigate to the given URL. Column ``Value`` must provide the URL. You might want to use variables in your URL-String,
       for instance your URL might look like this ``https://$(STAGE).earthsquad.global/``. It will be replaced
       during runtime of the test data with the value of ``STAGE`` from either Global settings or settings in the
       ``testCaseSequence``.
   * - click
     - Will click on the object specified by the ``locator``.
   * - clickIF
     - Will click on the object specified by the locator IF the field in testDataDict, that you enter in Column ``value``
       has a value. This small and simple extension can save you hours and hours of work in maintenance of testcases.
       Imagine you have 10 checkboxes, that in various combinations provide different test results, and you have to test
       all possible combinations. Using one column in your datafile for each checkbox and the ``clickif``, you can create
       your testCases in minutes instead of hours or days. Imagine 50 checkboxes - with ``baangt`` your effort is still
       just minutes.
   * - setText
     - Write the text given in column ``value`` to the element specified by ``locator``. Only rarely will you have fixed
       values. Usually you'll assign columns of the test data using variable replacement (e.g. ``$(POSTCODE)`` to set the
       text from column ``POSTCODE`` from the datafile into the destination element.
       In some cases we need to write any random value in the field or we need random value like name, string, interger,
       date, etc. for some other purpose for that we ``Random`` funtion. You will learn about it further in this document.
   * - setTextIF
     - Same as SetText, but will only do something in cases where there is a value in the datafile. Similarly to clickIF
       this little helper functionality can help you save hours and hours in creation and maintenance of rocksolid and
       bulletproof test cases.
   * - goBack
     - Trigger the "back"-Button of the browser.
   * - If/Else/Endif
     - The block between IF, ELSE and ENDIF is only executed when the condition evaluated by ``value|comparator|value2`` is
       true, for instance:

            $(POSTCODE) = 7040

            $(YEAR2DATE) > $(YEARTOMONTH)

            $(POSTCODE) (no comparison, no Value 2) --> checks for

       Additionally you can check for empty/non-existing values by comparing to ``None``.

       Another use of the If-Statement is with ``LocatorType`` and ``Locator`` and comparison. This can be used when you
       want conditional execution of a larger block of statements depending on an element present or not present.

       ``Else`` statement is only executed when if statement is not true.

   * - repeat / repeat-done
     - See details in <NestedLoops.rst>
   * - assert
     - Will retrieve value of element specified by ``locator`` and compare with reference value from ``value``.
      

   * - pause
     - Will pause for the number of secons in ``value``. Valid numbers are float, e.g. 2, 0.2, 0.1, 25
   * - waitForElementPresent
     - Will wait (and recheck) to find the element specified by ``locator``. You would use this, when you experience
       problems with page load.
   * - iban
     - Will create a random IBAN account number. ``value 2`` is the destination field of the test case structure. If you
       don't provide a field name (not necessarily one that exists in the input file. Can be any field name!) nothing will
       happen. If you provide input parameters in column ``value`` (``SWIFT`` and/or ``COUNTRY``) the IBAN will be created for that bank-code
       and/or country.
   * - pdfcompare
     - In a step before you must have downloaded a PDF-File. Before you can compare, you have to provide a reference PDF
       to upload. After the upload you'll receive a unique ID for this document. Paste this ID into the ``value`` field.
   * - CheckLinks
     - Whenever you enter this command, all (if any) links on the current page will be checked and the status of the
       link will be reported accordingly. Reporting format is:

       Links on <base_url>:

       <status>:<Link>

       You'll find the output in the Export sheet in the column "CheckedLinks", which will be created automatically.
   * - saveto (for Web test cases only)
     - Saves the value of the element specified by ``locatorType`` and ``locator`` into the field given in column ``value``.
            !!For this case, don't use variable syntax (``$(ColumnName)``) but put the column name only in field Value!!
   * - clear
     - ``Value`` must have the variable or column name, that should be cleared (without ``$(columnName)``,
       just ``columnName``
   * - switchwindow
     - Switches to a browser window. ``Value`` is the number of the window, that you want to switch to.
   * - setanchor
     - There are pages, where you'll not find good unique IDs or no nice way to locate elements. Setting an anchor can
       help in these cases. An anchor is an element, that can be located by CSS, ID or XPATH. After the anchor is set
       all future tries to locate an element will happen within the children of the anchor.

       To unset an anchor use setanchor without locator.

       setanchor can also improve the location performance, if you're dealing with really large pages.

            While an anchor is set, ALL location attempts of elements happen within the anchor's children. If you want
            to avoid that, use ```///``` (= 3 slashes instead of 2) to signal the logic to ignore the anchor.
   * - TCStopTestCase
     - Will stop the current test case from further execution
   * - TCStopTestCaseError
     - Will stop the current test case and set it's status to NOK
   * - address_create
     - provide an easy and easily extendable way to generate address data for a test case
       The following fields variable are stored in testcaseDataDict:

       CountryCode
       PostalCode
       CityName
       StreetName
       HouseNumber
       AdditionalData1
       AdditionalData2
       
       `value`  optional
         Default field-value: {'HouseNumber': '6', 'AdditionalData1': 'Near MahavirChowk', 'AdditionalData2': 'Opposite St. Marish Church', 'StreetName': 'GoreGaon', 'CityName': 'Ambala', 'PostalCode': '160055', 'CountryCode': 'India'} 

       These fields can be used as filter criteria in field value.
       Example value= `{CountryCode:CY, PostlCode: 7}`.



       Resulted field-value :{'HouseNumber': '6', 'AdditionalData1': 'Near MahavirChowk', 'AdditionalData2': 'Opposite St. Marish Church', 'StreetName': 'GoreGaon', 'CityName': 'Ambala', 'PostalCode': '7', 'CountryCode': 'CY'}

       `value2` optional
       If a prefix was povided in field Value2, the fieldnames will be concatenated with this prefix,
       e.g.if value2=`PremiumPayer_`, then the resulting field for CountryCode in testDataDict would become PremiumPayer_CountryCode.

Random
------
Sometimes we need random values like string, name, integer, float, date, time now in such case we have ``random``
functionality. It is used inside value column of and its structure is
``$(random{"type":<Type>},"min":<Minimum>,"max"<Maximum>,"format":<Format>)``. Only ``type`` field is compulsory and
every other fields are optional, also each fields are not useful in every type, e.g.- ``name`` type doesn't need any
other optional fields as they are use less for it. You can see fields and types supporting them.


.. list-table:: Fields supporting types
   :widths: 25 75
   :header-rows: 1

   * - Field
     - Type

   * - type
     - This field is compulsory and base of ``random`` funtionality.
       string, name, int, float, date, time are the types currently supported

   * - min
     - string, int, float, date, time are the types supporting this field. Value of min will be with respect to its
       type like value for string will be an integer containing minimum number of characters in string and for all other
       it will be lower limit, for int it will be an integer & float for float, for date value will be a date e.g. -
       "31/01/2020" and for time it would look like "20:30:59"

   * - max
     - string, int, float, date, time are the types supporting this field. Value of max will be same like in min,
       value for string will be an integer containing maximum number of characters in string and for all other it
       will be upper limit, for int it will be an integer & float for float, for date value will be a date e.g. -
       "01/06/2020" and for time it would look like "13:10:30"

   * - format
     - date, time are the only types supporting format field. In above date examples date is in %d/%m/%Y format and
       time is in %H:%M:%S format. Here "%d" stands for the day, "%m" stands for month, "%Y" stands for year including
       century e.g.- 2020, if you want only year you can use "%y" e.g. 20. If you use min and max fields in date, time
       then you must input its written format in format field, default will be ""%d/%m/%Y" for date. Now if you want
       date with "-" as seperator you can write format as "%d-%m-%Y" so the output would be like "31-01-2020".

       `examples`
        $(random{"type":"name"})
        $(random{"type":"string", "min":10, "max":100})
        $(random{"type":"int", "min":10, "max":100})
        $(random{"type":"float"})
        $(random{"type":"date", "min":"20/1/2020", "max":"30/6/2020", "format":"%d/%m/%Y"})
        $(random{"type":"time"})
        $(random{"type":"time", "min":"10.30.00", "max":"15.00.00"}, "format": "%H.%M.%S")