The `discover_url` function should not fail, instead it should return
empty results. In case of failure, it's impossible to find out what
went wrong as we don't log any details, thus it might happen that
`avocado list` shows tests, which are not found during `avocado run`.
This patch temporarily logs reason into the `avocado.app.exceptions`
and traceback into the `avocado.app.traceback` logger. Booth are
enabled by default, but the plan is to make these optional and
show only the `exceptions` by default.
Signed-off-by: NLukáš Doktor <ldoktor@redhat.com>

This function is a wrapper around logging.getLogger and it uses the
same format as log_exc_info. It's useful for logging exception details
and other explanation to specific logger.
Signed-off-by: NLukáš Doktor <ldoktor@redhat.com>

When exception travels across multiple try/except blocks it's hard to
find where the "log_exc_info" was called from. This information is
not part of the traceback but is quite good place to see why
is the exception harmful.
Signed-off-by: NLukáš Doktor <ldoktor@redhat.com>

API review: implement relative imports also on avocado.core.*

The same approach has already been applied to avocado.utils itself
and it's documented at:

https://www.python.org/dev/peps/pep-0328/Signed-off-by: NCleber Rosa <crosa@redhat.com>

API Review: add test methods for SKIP/FAIL/ERROR themselves

setup.py: add missing module avocado.utils.external

It was previously not possible for a test to skip itself (due to say,
missing requirements) during the setUp() phase. Any exception caught
at this point was reflected as a test failure.
Signed-off-by: NCleber Rosa <crosa@redhat.com>
Signed-off-by: NLucas Meneghel Rodrigues <lmr@redhat.com>

Instead of playing with core exceptions or downgrading those exceptions
to the base Test API, let's allow users to do so with convenience
methods.

The example tests now make use of those, and can now remain in the
examples directory instead of the former proposal of turning them
into "functional test assets" and moving them to the selftests
directory.
Signed-off-by: NCleber Rosa <crosa@redhat.com>

The new location was not reflected on the setup.py script, resulting
in the module not being present after installation.
Signed-off-by: NCleber Rosa <crosa@redhat.com>

Add option to read a custom configuration from a file ǘ[v2]

avocado.core.remote.runner: When setup/teardown fails, exit gently.

When setup() or tear_down() fails, Avocado
will provide a gentle error message and a proper exit code and
put the traceback in the test log.

  ./scripts/avocado run --remote-host nowhereland passtest
  LOGIN      : rmoura@nowhereland:22
  Avocado job failed: JobError: Name lookup failed for nowhereland

Prior to this commit, when setup or tear_down failed,
Avocado dumps the traceback and prints that it crashed, which
can potentially confuses the user.
Signed-off-by: NRudá Moura <rmoura@redhat.com>

Use command line --config to read a custom configuration from a file.
Note this option is for the avocado application, so it has
effect for all subcommands.

Example:

$ avocado --config /var/tmp/avocado.conf config
Config files read (in order):
/home/rmoura/Work/avocado/etc/avocado/avocado.conf
/home/rmoura/Work/avocado/etc/avocado/conf.d/gdb.conf
/var/tmp/avocado.conf
...

Also, update man-page about the new option --config.
Signed-off-by: NRudá Moura <rmoura@redhat.com>

To introduce the command option --config, it requires to use
the _process_config_path() method outside avocado.core.settings, so
let's make it public as process_config_path().
Signed-off-by: NRudá Moura <rmoura@redhat.com>

Documentation Review (3rd round)

As this pretty much documents how Avocado saves the results, it's
pretty much a reference document.

The location of the job logs is pretty clear in the Getting Started
section when the user runs their first tests, and it's pretty obvious
even for 1st time users not even reading the documentation.

If users want to understand more about it, or customize the location,
the Reference Guide is indeed the place to go.
Signed-off-by: NCleber Rosa <crosa@redhat.com>

Pretty obvious typo with an extra "d".
Signed-off-by: NCleber Rosa <crosa@redhat.com>

It no longer attempts to encode any kind of information. Let's also
give examples on how the full and the short form of the SHA1 strings
are used.
Signed-off-by: NCleber Rosa <crosa@redhat.com>

This fixes a bug introduced by cb751ea5.
It turns out that .itervalues() is a bad idea, given that the
args dictionary is modified by plugins, leading to a bug when
we have multiple test source plugins enabled at once.

I'm sorry I didn't notice this before the commit was merged.
Signed-off-by: NLucas Meneghel Rodrigues <lmr@redhat.com>

Implement a feature to skip notifying broken plugins on
stderr. Let's say a user has a broken plugin that can't
be fixed right now, and he/she doesn't want to be bothered
by having it notified in stderr all the time avocado is
executed, add a configuration option that allows you to
selectively ignore plugins to display errors in stderr.

The reason why the feature is configurable is that we
want users to be notified when a new plugin is present
and for some reason is also broken, this finer grained
control is more useful to users IMHO.
Signed-off-by: NLucas Meneghel Rodrigues <lmr@redhat.com>

Use python's ast module to safely evaluate the list values.
Signed-off-by: NLucas Meneghel Rodrigues <lmr@redhat.com>

API Review (2nd round, 2nd batch) - All commits but Exceptions

It was mentioned that we should think of avocado.utils as a subproject
that happens to live in the same source tree. So, it should not make
use of any avocado module. If that's the case, maybe we don't want to
keep referencing 'avocado.utils' in the utils module themselves.

This is in accordance with PEP-0328[1]

[1] - https://www.python.org/dev/peps/pep-0328/Signed-off-by: NCleber Rosa <crosa@redhat.com>

This means also moving its dependencies, namely spark and gdbmi_parser,
to a place under avocado/utils. I've chosen to add another level here
to clearly identify those deps as 3rd party external modules that are
reused in Avocado.
Signed-off-by: NCleber Rosa <crosa@redhat.com>

The avocado.settings module is not intended to be used by tests but
by the framework itself. So, let's move it to avocado.core.
Signed-off-by: NCleber Rosa <crosa@redhat.com>

This is also a module that shouldn't be used directly by tests,
as tests themselves have attributes with the right data directories
already ready to use.

So, let's move it to avocado.core.
Signed-off-by: NCleber Rosa <crosa@redhat.com>

There's no current use case for direct use of the multiplexer APIs
from test code, so let's move that to avocado.core.
Signed-off-by: NCleber Rosa <crosa@redhat.com>

It looks like there's no need for the logging configuration and the
application of that configuration to live under avocado main module,
so let's move it to avocado.core.log.

Also, there also seems to be no need for the configuration to be
applied at the main module import time.

Since when the avocado command line test runner is run and also
when a test is run "directly" results in instantiating an
avocado.core.app.AvocadoApp object, this looks like the best place
for the logging configuration to actually be performed.
Signed-off-by: NCleber Rosa <crosa@redhat.com>

Even though aexpect is possibly a good candidate for the avocado.utils
namespace, there are plans to actually move it into a standalone Python
project/module. So, since no tests are currently using the module
directly, let's move to avocado.core.

It can not be removed at this point because the avocado-virt extension
uses it. A PR is being sent to avocado-virt to sync with this change.
Signed-off-by: NCleber Rosa <crosa@redhat.com>

The initial idea about the avocado.restclient namespace was that
eventually users could write scripts using that as an API to
interact with avocado-server using Python code.

While the idea is still valid, the avocado-server interface is
a simple and standards compliant RESTful interface. Thus, users
can still easily interact with it without us having to support
a formal Python API at this point.

In the future, if need arises, we can improve the Python REST
client API and promote it to a public namespace.
Signed-off-by: NCleber Rosa <crosa@redhat.com>

avocado.utils.software_manager: Check if yum module is present

When using the software_manager component on a Red Hat like distro,
if the yum module for Python is not installed, log the information
as an error message and use the basic support from rpm/yum.

Why this?

If the module yum is not installed (for example, in a virtualenv),
the software_manager component will not traceback when creating
an instance of YumBackend and only the method provides() will be disabled.
Signed-off-by: NRudá Moura <rmoura@redhat.com>

For a while we have been using code similar to this:

def load_plugins(self, args):
    for key in args.__dict__.keys():
        if key.endswith('_loader'):

One could argue that the sufix check is not quite elegant
or correct, so we can remove that and get straight to the
business of checking the actual loading class we're interested
in. This PR changes all the occurrences of that practice inside
the avocado code.

Changes from v2:
 * Use iteritems() instead of .keys(), as suggested by ldoktor.
Signed-off-by: NLucas Meneghel Rodrigues <lmr@redhat.com>

Documentation Review (2nd round) - (v2)

The text means that Avocado is made of the test runner, libs, etc.
So, that should really be written as "composed of" instead of
"composed by".

Just to be extra clear, Avocado is "composed by" the Avocado
Development Team.
Signed-off-by: NCleber Rosa <crosa@redhat.com>

The reference documentation now contains a section on the libraries and
APIs, giving information on where those can be found in the `avocado`
namespace, and their respective API stability promises.

Then, instead of giving too much information about it in the introductory
section, let's just link to the reference section if the user wants to
know more about it.

Changes from v1:
* Fix typo spotted by Lucas (s/will/you).
Signed-off-by: NCleber Rosa <crosa@redhat.com>