to the specification described below.

  Minimal version

  If you don't need anything fancy, then this is the minimalistic version of the

  output which, at the same time, is valid for results reporting in Taskotron::

  .. Note::

    ``item``, ``type``, ``outcome`` and ``checkname`` are just some of the

  Full version

  Although the minimal version of the output is sufficient, you can use

  additional fields to provide more information::

  results as such.

  The full list of fields with a pre-defined meaning is available at

  :py:attr:`libtaskotron.check.RESERVED_KEYS`.

  ``package`` in the above example), which will get stored in ResultsDB, and can

  be then used for searching. Those fields will be specific for your task and you

  can give them any meaning and use them for any purpose that you need.

  .. note:: Taskotron also includes support for plain STI tests (i.e. specific,

     not generic tasks). However, this support is experimental and not maintained

     at the moment. There are other systems which handle this area, at least in

  .. _taskotron-sti:

    STI.

  * The playbook's exit code is not used for generating PASS/FAIL result

  Read :doc:`writingtasks` to see some examples of the format described here.

  .. _ResultsDB: https://fedoraproject.org/wiki/ResultsDB

  from libtaskotron import config

  from libtaskotron.exceptions import TaskotronDirectiveError, TaskotronValueError

  from libtaskotron.logger import log

  import resultsdb_api

  DOCUMENTATION = """

              check_details = check.import_YAML(params['results'])

              log.debug("YAML output parsed OK.")

          except (TaskotronValueError, IOError) as e:

          for detail in check_details:

              if not (detail.item and detail.report_type and detail.checkname):

              directory

          :param str ipaddr: IP address of the machine the task will be run on

          :param bool root: whether to run as ``root`` for local execution mode

          :raise TaskotronPlaybookError: when the playbook is not syntactically

              correct

          '''

              # not just in the first?

              playbook = yaml.load(playbook_file.read())[0]

              if playbook.get('vars',{}).get('taskotron_generic_task', False):

                  exec_tasks = 'tasks_generic.yml'

                  log.debug('Playbook %s is a generic task', test_playbook)

              else:

                  exec_tasks = 'tasks_sti.yml'

                  log.debug('Playbook %s is an STI task', test_playbook)

              keepalive = playbook.get('vars', {}).get(

              signal.signal(signal.SIGTERM, self._interrupt_handler)

              output, _ = os_utils.popen_rt(cmd, cwd=ansible_dir)

          except subprocess.CalledProcessError as e:

              log.error('ansible-playbook ended with %d return code',

                        e.returncode)

          raise exc.TaskotronInterruptError(signum, signame)

      def _report_results(self, test_playbook):

          results_file = os.path.join(self.arg_data['artifactsdir'],

              test_playbook, 'taskotron', 'results.yml')

      def execute(self):

          '''Execute all the tasks in the taskdir

          :rtype: bool

          '''

          test_playbooks = fnmatch.filter(os.listdir(self.arg_data['taskdir']),

          log.info('Running task on machine: %s', ipaddr)

          for test_playbook in test_playbooks:

              try:

              except exc.TaskotronInterruptError as e:

                  log.error('Caught system interrupt during execution of '

                      test_playbook, e)

                  break

              except exc.TaskotronError as e:

                      test_playbook, e)

              finally:

                  if self.task_vm is not None:

                      self.task_vm.teardown()

      # start execution

      executor = Executor(arg_data)

      # finalize

               datetime.datetime.utcnow().strftime('%Y-%m-%d %H:%M:%S UTC'),

               arg_data['artifactsdir'])

          # the tradeoff here is that we need to run with root=False

          # (non-default)

          # FIXME: We currently have no idea whether the test playbook passed

          # or failed, because we ignore the inner playbook's exit status. So

          # we can't really verify here whether everything worked ok.

  from libtaskotron import check

  from libtaskotron import config

  class StubConfigParser(object):

          for key in self.cd.keyvals.keys():

              assert call_data[key] == self.cd.keyvals[key]

      taskotron_generic_task: true

    tasks:

      - debug:

  '''

              self.arg_data

      def test_report_results_missing_file(self, monkeypatch):

      def test_run_playbook(self, monkeypatch):

          '''A standard invocation of ansible-playbook'''

          mock_popen = mock.Mock(return_value=('fake output', None))

          monkeypatch.setattr(os_utils, 'popen_rt', mock_popen)

          # must return playbook output

          assert output == 'fake output'

          '''Execution using local mode'''

          mock_spawn_vm = mock.Mock()

          monkeypatch.setattr(executor.Executor, '_spawn_vm', mock_spawn_vm)

          monkeypatch.setattr(executor.Executor, '_run_playbook',

              mock_run_playbook)

          mock_report_results = mock.Mock()

              mock_report_results)

          assert self.executor.arg_data['local'] == True

          mock_spawn_vm.assert_not_called()

          mock_run_playbook.assert_called_once()

          assert mock_run_playbook.call_args[0][1] == '127.0.0.1'

          '''Execution using ssh mode'''

          mock_spawn_vm = mock.Mock()

          monkeypatch.setattr(executor.Executor, '_spawn_vm', mock_spawn_vm)

          monkeypatch.setattr(executor.Executor, '_run_playbook',

              mock_run_playbook)

          mock_report_results = mock.Mock()

          self.executor.arg_data['ssh'] = True

          self.executor.arg_data['machine'] = '127.0.0.2'

          mock_spawn_vm.assert_not_called()

          mock_run_playbook.assert_called_once()

          assert mock_run_playbook.call_args[0][1] == '127.0.0.2'

          '''Execution using libvirt mode'''

          mock_spawn_vm = mock.Mock(return_value='127.0.0.3')

          monkeypatch.setattr(executor.Executor, '_spawn_vm', mock_spawn_vm)

          monkeypatch.setattr(executor.Executor, '_run_playbook',

              mock_run_playbook)

          mock_report_results = mock.Mock()

          self.executor.arg_data['local'] = False

          self.executor.arg_data['libvirt'] = True

          mock_spawn_vm.assert_called_once()

          mock_run_playbook.assert_called_once()

          assert mock_run_playbook.call_args[0][1] == '127.0.0.3'

      def test_execute_more_playbooks(self, monkeypatch):

          '''Should execute all found playbooks'''

          monkeypatch.setattr(executor.Executor, '_run_playbook',

              mock_run_playbook)

          mock_report_results = mock.Mock()

              mock_report_results)

          self.playbook.copy(self.taskdir.join('tests_copy.yml'))

          assert mock_run_playbook.call_count == 2

          playbooks = [

              mock_run_playbook.call_args_list[0][0][0],

          assert 'tests_copy.yml' in playbooks

      def test_execute_error(self, monkeypatch):

          mock_run_playbook = mock.Mock(side_effect=exc.TaskotronError)

          monkeypatch.setattr(executor.Executor, '_run_playbook',

              mock_run_playbook)

          monkeypatch.setattr(executor.Executor, '_report_results',

              mock_report_results)

          mock_run_playbook.assert_called_once()

          mock_report_results.assert_not_called()

      def test_execute_interrupted(self, monkeypatch):

              mock_report_results)

          self.playbook.copy(self.taskdir.join('tests_copy.yml'))

          mock_run_playbook.assert_called_once()

          mock_report_results.assert_not_called()

          for key in self.cd.keyvals.keys():

              assert call_data[key] == self.cd.keyvals[key]

      def test_both_file_and_results(self, monkeypatch):

          ref_input = {'results': 'foobar', 'file': 'foo.bar'}

          with pytest.raises(TaskotronDirectiveError):