# Pluglet API tests specification.

    Subject:
          The subject of testing is  Pluglet API
    Goals:
          Goals of testing - to detect errors in pluglet api
          implementation and in  functioning of this api in mozilla.

    This API is divided on two part:
     - called by browser (latter called Pluglet side API)
     - called by pluglet (latter called Browser side API).

    Basic template of runtime scenario of calling of
    Pluglet side API methods.

    Scenario variations:
    - basic straight scenario - without and with calls caused
      by data to be loaded for pluglet
    - behaviour of the same pluglet instance in case of back-forward
    - re-creating pluglet instance after reload

    The different pluglets display types:
    - embedded
    - embedded hidden
    - full page pluglets

    Additional situations:
    - incorrect environment (for example PLUGLET)
    - absence of pluglet
    - incomplete pluglet (for example without instance class)
       Comment: in these cases (1-3) we need to ensure that mozilla doesn't fall
    - different pluglets having pluglet instances (or other classes)
       with equal names
    - finding and loading pluglets based on mime type of data and
       handled mime types of pluglet

    Security issues:
    - based on fact that the pluglets are run in java environment
      the tests should check the correspondence of actual runtime
      constrains to specified constrains.

    So, the sets of tests to develop:
    1. scenario tests for each combinations of scenario variations and pluglet display type
       The sequence of calls of pluglet side API methods should be corresponding to
       situation (in correct order, without lacks and additional non-specified calls)
    2. the tests of correctnesses of passed in values and objects in situations of
       different scenario and pluglet display type
    3. returning (for cases when non-void return value is specified) by pluglet side api different values
       from set of expected values, boundary and non-correct values (from point of
       view of functional sense of return value)
    4. the tests of Browser side API
       (passed in objects (for example PlugletManager) as well as
       objects by request (for example PlugletTagInfo))
       - the passing in different sets of parameters, including
         boundary and non-correct values(from point of view of functional sense of parameters)
       - checking that correct values are returned (if applicable)
       - checking that correct action are performed (if applicable)
    5. the tests for non-falled (and/or correct) behaviour for "additional" situations
    6. the more typical subset of 1,2,3 tests in cases of more than one pluglet
       instance (in parallel ( on the same page) as well as in sequence (pluglet on the next page))
    7. the more typical subset of api tests in multithreading mode - calling the browser side
       api methods simultaneously from different threads
    8. security tests

    Test space organization:
    - The src, build, config, util, log and doc directories.
    - All necessary files should be compiled or copied into the build directory.
    - All common perl scripts should be placed in the util directory
    - Recursive organization of makefiles.
    - The top-level makefile is placed to src/org/mozilla/pluglet/test/basic
    - Top package for all test classes is org.mozilla.pluglet.tests.basic
    - The suffixes are like to
       .scenario
       .security
       .security.automated
       .returns
       .params
       .api
    - Every test is like to consist of necessary java files, html file to cause
      pluglet instantiation, test properties file - needed settings
      for test if they are different from common settings (as example $DELAY for stress
      tests or $PLUGLET for testing incorrect value of this one
      may differ from common settings) and test parameters file - the parameters that identify
      concrete test case in set of tests with the same structure.
    - Perl script autorun.pl is used to invoke automated test cases
      and to record their results