Package: cubicweb-narval
SummaryNarval is a CubicWeb based framework to run automated tests. It
consists in 2 parts:the narval cube which implements the schema and some web UIs to
create, configure and run test campaigns, andthe narval bot which waits for jobs to execute. It polls the
CubicWeb application for new tasks to run (called Plans in narval’s
jargon), and executes them when some are waiting for exectution.The narval bot communicates with the web application by doing HTTP(S)
requests.Recipe and PlanThe schema of the cube defines 2 entities:Recipe:represents a Python script to be executed to run the tests,Plan:represents the execution of a Recipe; it has a workflow (with
the following states: ‘ready’, ‘running’, ‘done’, ‘error’,
‘killed’); when executed, the execution log file (stdout and
stderr) of the recipe is attached to thePlan(via theexecution_logrelation).Execution process of a RecipeIn order to run aRecipe, one must create aPlan(an execution
plan).In the web UI, this can be done via theStart Planbutton on aRecipemain
view. This creates a newPlanentity (which references theRecipe) in thereadystate.Then, as soon as the narval bot asks the application for waiting jobs
(i.e.Planin thereadyworkflow state), it eventually gets thePlaneid.The narval daemon then spawns a new process to manage the execution of
the plan in a separate process; the executed command is something like:narval run-plan narval https://webapp.com/3071/ --uid narval --threads 1 --max-reprieve 1min --log-threshold DEBUGwhere3071is the eid of thePlanto be executed. Theoptionsattribute of thePlan(which is a string of the form:“key1=value1nkey2=value2n[…]”) is converted into command line
arguments (–key1 value1 –key2 value2 […]) to be passed to therun-plancommand.Thisrun-plannarval command retrieves the parameters of thePlan(the Python code to be executed and some execution options), then:it fires thestartworkflow transition (by means of a HTTP request),it executes theRecipePython script (by means of anexecfilecall); the script is executed with a globals (and locals)
dictionary defining one variable,plan, which references a Python
object having the folowing attributes:cnxh: an HTTP connection handler allowing to make requests to the
web application from the executed script,plandata: a dictionary holding the executedPlanparameters,options: a dictionary with all defined options of thePlan,name: the name of theRecipeto be executed,script: a string with the Python script to run.Warning: the Python script is executed in the context of therun-planPython process.it fires the transition:endif the execution went fine (did not crash),killif the execution exceeded some resource limits (memory, execution time),failif some uncatched Exception has been raised.When thenarval run-planshell command returns, thebotchecks for
the return code, retrieves thestdoutandstderrof the process and
uploads them as theexecution_logof thePlan, so the user can have
access to the full execution log (print statements, logging messages,
etc.).PluginsUser can write plugins that will be importable from recipes when
executed bynarvalrun-plan. The normal way is to write a cubicweb
cube in which you add a_narvaldirectory where you can add python
modules and packages. When run from source directory, the_narvaldirectory of every available cube will be added in the PYTHONPATH of
thenarvalcommand.Please refer to theapycotcube as an example.