.. Copyright (C) ALbert Mietus, SoftwareBeterMaken.nl; 2014, 2015. Part of Pathways project -*- coding: utf-8 -*-

=================
Pathways glossary
=================

.. glossary::

   ATS
   ATSes
   Automatic Test Script
   Automated Test Script
      An *ATS* is a scripted test to *'prove'* (or *disprove*) a part of the developed :term:`PUT`
      works correctly. As such it delivers only **one bit** of information: verified of fail. This
      implies it does verify (check) the results of test.

      An *ATS* typically consists of a number of steps, like starting a session, doing several
      operations, and verifying the results. Each step, not only the verification once, have to be
      successful to get an 'OK'.

   ATSfile
   ATStest
      As a single **ATSfile** can contain several **ATStest**\s and both are typically called :term:`ATS`, the suffixes
      *file* and *test* are sometime used distinguish them.

   TsTbrick
   brick
      A (test) **brick** is the basic, *reusable*, unit to build (all) :term:`ATS`\es. A *brick* offers a
      conceptual, *human oriented* set of commands to the :term:`ATS`; so the upper-interface of
      the brick is *independend* of the technology of the PUT.

      Typically, the brick's implementation should also not depend on (PUT-implementation &
      -interfacing) technology depending; it makes the *brick* better reusable.
      |BR|
      There are some brick-like unit for that; see: :term:`cobblestone`, :term:`gate`


   gate
      During the executing an :term:`ATS` all kind of commands and results are passed to and from
      the :term:`PUT`, by an interface called the *gate*. The implementation of a *gate* is
      typically specific to the technology of that that :term:`PUT`. At the same time, the role of
      the *gate* is to hide that technology. Such that :term:`cobblestone`\s are less depending on
      that specific :term:`PUT` and :term:`brick`\s not at all.

   interface
      .. deprecated:: pre-alfa
         Old name for :term:`gate`; do not use anymore


   cobblestone
      A *rough* kind of brick, for special cases. By example to extend a :class:`pathways.puts.put`

      A real brick has a functional interface; with cobblestone a second, *lower-level* way to interact with
      the PUT possible. Which isn't used in most tests, but can be convenient in exceptional cases.  It
      better to have a test, that scripted with to many details, then having no option to automate it.

      This is best explained with a simple web-calculator. A (human) user can control it  by clicking
      buttons, reading or entering some text, etc. With a cobblestone that level of control
      is available for a script. Although, a good test isn't build out of this kind of commands. They
      use more functional commands, like: 'add two numbers'; a typical brick-command.

      With a cobblestone those smaller *steps*, like *clicking*, entering test and reading values are
      possible. Just for in case they are needed to test the exception.

      Secondly, cobblestones are often used to script real bricks. By example the 'add two numbers'
      bricks-command can be implemented by entering a some strings, clicking a few buttons, and reading
      the result.


   PUT
   Product Under Test
      Depending on the context, the term **put** can refer to the actual product that is tested, or
      to the proxy-object that represents it.

      The proxy-object is typically a subclass of :class:`pathways.puts.put`, or one of it subclasses in
      :mod:`pathways.puts`, which can be extended with :term:`cobblestone`\s


   feed
      The **feed** part of a test-vector are used as input for the :term:`PUT`.


   expected
   expected results
      The **expected results** (or shortly: **expected**) part of a test-vector specify the values
      that the :term:`PUT` should return. They are (smartly) compared with the *actual results*.


   actuals
   actual results
      This are the values the :term:`PUT` outputs and are compared to the :term:`expected results`
      to verify correctness.

      Note that the compare has to be *smart*; not all parts of the output are relevant. By example
      an (generated) XML-file typically contains a datestamp; which will vary each run. So that
      part is typically filtered out


   conditions
      .. versionadded:: Future
         Currently no support is available for conditions. Only :term:`feed` and :term:`expected` can be used now.

      Some tests may need more complex validations then comparing the :term:`expected results` with
      the :term:`actual results` after giving the :term:`PUT` an input :term:`feed`. By example,
      real-time demands may specify a maximum delay.  This kind of conditions can be given in the
      **condition** part of a test-vector.

   TstVector
      .. todo:: TstVector

   fixture
   fixtures
     .. todo :: fixture