//////////////////////////////////////////////////////////////////////////////
//                                                                          //
//                          TOL-Tester                                      //
//                                                                          //
//////////////////////////////////////////////////////////////////////////////

==============================================================================
A) Definicin de TOL-Tester
==============================================================================

Se trata de un sistema estndar de chequeo del comportamiento del lenguaje TOL
y de las herramientas relacionadas como TOLBase. Antes de publicar cada nueva
versin se debe comprobar que TOL acta como se espera lo cual no suele ser 
nada trivial dado el extenso nmero de aplicaciones del lenguaje.


==============================================================================
B) Estructura de TOL-Tester
==============================================================================

En el directorio raz se encuentran los ficheros TOL comunes a todas las 
bateras de tests adems de ste fichero de ayuda.

  - _testCommon.tol : Estructuras y funciones auxiliares comunes
  - _testConfig.tol : Parmetros de configuracin comunes
  
Los tests se encuentran clasificados en directorios dependiendo del PRODUCTO
concreto que se intenta probar. Dentro de cada producto existirn directorios 
dedicados a las distintas bateras de tests que lo comprueban, en virtud del 
TEMA a chequear. El par PRODUCTO/TEMA define una BATERA de tests 
relacionados entre s.

Dentro de cada batera puede haber una estructura totalmente libre de 
subdirectorios que se recorrern recursivamente en busca de archivos
test.tol los cuales se interpretarn como cada uno de los tests particulares
de la batera asociada. De esta manera cada batera se puede adaptar a sus
necesidades de forma muy flexible sin perder generalidad ni facilidad de uso.

A cada uno de los paths relativos a la batera que contengan un test le 
llamaremos BASE del test. Es decir los tests se definen en los ficheros de 
la forma  PRODUCTO/TEMA/BASE/test.tol

Por el momento existen los siguientes productos y temas
  
 -tol: los tests acerca del lenguaje propiamente dicho sin que intervenga
       ningn mdulo auxiliar
      
   -tol/Bugzilla:         comprueba que los bugs resueltos siguen funcionando
   -tol/ARIMA:            Tests de simulacin acerca de modelos ARIMA
   -tol/TimeSetCoherence: Tests de simulacin acerca del lgebra del tiempo
   
 -tolcon: los tests acerca del ejecutable de TOL en modo de consola
   
   -tolcon/Bugzilla: comprueba que los bugs resueltos siguen funcionando
    
 -toltcl: los tests acerca de la API de comunicacin de TCL con TOL para la
          construccin de interfaces

   -toltcl/Bugzilla: comprueba que los bugs resueltos siguen funcionando
                     
 -toldb: los tests acerca de la conexin de TOL con bases de datos
  
   -toldb/Bugzilla: comprueba que los bugs resueltos siguen funcionando


==============================================================================
B) Modo de empleo de TOL-Tester
==============================================================================

En cada directorio existe un archivo _tolTester.tol que se encarga de realizar
todo lo necesario, y que debe ser compilado con la versin de TOL que se desea
comprobar. 

Antes de hacerlo es conveniente repasar la configuracin de la lista de 
bateras de tests que se desean comprobar en el conjunto TestConfigTable de
registros con estructura strBatteryConfig definida en _testCommon.tol

Los test se pueden ejecutar una o varias veces o incluso ninguna si as se
especifica en TestConfigTable, para facilitar de este modo la adaptacin a 
diferentes situaciones de chequeo de cada una de las bateras. Por ejemplo,
tras un cambio profundo de TOL o al publicarse una nueva versin sera
conveniente realizar un chequeo exhaustivo que puede durar varias horas, 
pero tras una leve modificacin quizs slo queremos probar alguna batera
en concreto o un poco de todo, de forma que dure apenas unos minutos. Nos 
referiremos a cada una de estas ejecuciones con el trmino ITER.

Opcionalmente, un test puede tener un fichero de parametrizacin PARAM que  
se puede usar, por ejemplo, para modular el volumen de las simulaciones 
efectuadas. 

==============================================================================
C) Visualizacin de resultados
==============================================================================

La mayora de los tests sern deterministas en el sentido de que slo pueden
salir bien o mal, pero otras veces no es posible determinar tal cosa y tan
slo se puede dar una medida probabilstica e incluso subjetiva de la calidad
obtenida.

El programa ir sacando una traza del cada test con el resultado de su 
calidad en una norma probabilstica de 0 a 100% as como el tiempo empleado.

Al final de cada batera se dar un pequeo resumen de sus resultados y una 
vez terminada la compilacin es posible ver sendos resumenes a nivel de 
batera (AllReport) y a nivel de test (AllDetail) donde se puede encontrar
informacin adicional acerca de los tests que no hayan dado el resultado 
esperado.

Cada test genera de forma automtica un directorio de resultados localizado 
en PRODUCTO/.result/test_YYYY_MM_DD_HH_MM/[PARAM_]TEMA/BASE[/ITER] en el que 
se almacenan estos ficheros
  
  - test.bat: fichero de llamada del test por si se quiere 
                          reproducir posteriormente
  - test.log: fichero de salida estndar de la ejecucin para
                          buscar posibles errores o anomalas 
  - test.bst: fichero de resultados utilizado despus para generar
                          las tablas de resmenes.

Nota: YYYY_MM_DD_HH_MM significa ao,mes,da,hora,minuto 

==============================================================================
D) Funcionamiento interno de TOL-Tester
==============================================================================
  
Cada test retornara un Set de estructura strTestStatus definida en 
_testCommon.tol con la informacion de los resultados propiamente dichos y 
elementos desriptivos y auxiliares. La llamada a cada uno se har usando el 
sistema operativo para arrancar una nueva sesin TOL para evitar por un lado 
efectos colaterales entre los distintos tests as como salvaguardar el proceso
de lanzamiento de posibles cadas provocadas en uno de ellos.

El que invoca cada test (tol_tester) se encarga de recolectar las metricas que
son generales para todos los tests adems de la devuelta en el strTestStatus, 
confeccionando un conjunto de estructura strTestMetric definida en 
_testCommon.tol, en la que se incluye la informacin heredada de la batera a 
la que pertenece as como de los cambios de estado de ciertas variables: 
tiempo y memoria empleados, nmero de errores y warnings, etc.

Cuando se finaliza un batera concreta se genera un conjunto con estructura
strTestBattery definida en _testCommon.tolen el que se incluye informacin 
sobre la propia definicin de la batera, sobre las condiciones de ejecucin 
del test (sistema operativo, versin del compilador y de TOL, momento de 
inicio), as como algunos estadsticos de resumen de los resultados obtenidos.


==============================================================================
E) Tareas por hacer en TOL-Tester
==============================================================================

1- En una etapa posterior podria ser interesante almacenar toda la informacion
en una base de datos a modo de realizar queries avanzadas que permitan hacer 
un diagnostico automatico del resultado de los tests.

2- En ocasiones la ejecucin de un test puede ocasionar un ciclo infinito o
que se quede a la espera por cualquier motivo (especialmente en windows que
tiene por costumbre sacar ventanas para cualquier tontera). En tales casos 
sera necesario poder lanzar los tests como hilos y quedar a la espera hasta
que el test acabe o transcurra un tiempo mximo. Mientars no sea as los tests
se tendrn que seguir lanzando bajo la tutela de un operario.

3- Otra posibilidad relacionada con la anterior sera lanzar los tests contra
otras mquinas de forma remota utilizando TRC o cualquier otro mtodo, para
liberar recursos en la mquina cliente y dedicar mquinas especficas a las 
tareas de chequeo de versiones de TOL.

