The command line options and documentations refer to "process",
"applications", etc. It's more natural to think and describe them as
"executables" instead.
Signed-off-by: NCleber Rosa <crosa@redhat.com>

The command line options and documentations refer to "binaries" a
lot, with options descriptions such as BINARY_PATH. It's more
natural to think and describe them as "executables" instead.
Signed-off-by: NCleber Rosa <crosa@redhat.com>

API docs: generate separate sections for the 3 modules boundaries

Avocado currently has 3 very distinct namespaces boundaries: test
API, utils, and core. Let's create 3 separate sections so that
users know which one(s) they could use for a given task.
Signed-off-by: NCleber Rosa <crosa@redhat.com>

The introduction was meant to be kept shorter, without the bullet
point items, because proper descriptions are in the inner sections.
Signed-off-by: NCleber Rosa <crosa@redhat.com>

Documentation Review (4th round, v2)

Whenever we use remoter.Remote(), our wrapper to fabric
inside tests, we end up losing information that could
be used for debugging purposes. Let's introduce an
remote related log to the avocado test results dir
(remote.log), that will be populated if
remoter.Remote() is used.

With this patch, tests that use remoter.Remote()
(avocado-virt) will have better debugging information
available.
Signed-off-by: NLucas Meneghel Rodrigues <lmr@redhat.com>

In order to troubleshoot more effectively problems
happening in remote/vm operations, make all output
coming from fabric and paramiko to a 'remote.log'
file in the top level job directory.
Signed-off-by: NLucas Meneghel Rodrigues <lmr@redhat.com>

In order to let multiple loggers to get the same information,
let the LoggingFile object to accept a list of loggers, rather
than a single one.
Signed-off-by: NLucas Meneghel Rodrigues <lmr@redhat.com>

This is obviously about Avocado, and just having "Configuration" makes it
easier on the brain and on the eyes.
Signed-off-by: NCleber Rosa <crosa@redhat.com>

As listing plugins is already mentioned in other sections, and
documentation on writing a plugin is probably the last thing a regular
user would look for.
Signed-off-by: NCleber Rosa <crosa@redhat.com>

This basically brings changes in wording and updates to command line
outputs.
Signed-off-by: NCleber Rosa <crosa@redhat.com>

This basically brings changes in wording and updates to command line
outputs.
Signed-off-by: NCleber Rosa <crosa@redhat.com>

Into a new section named "Running Tests Remotely".
Signed-off-by: NCleber Rosa <crosa@redhat.com>

This doesn't seem to be the best place for this piece of information.
Let's remove it for now, and it may (or may not) have a place
somewhere else.
Signed-off-by: NCleber Rosa <crosa@redhat.com>

At its core, what's really important to get accross is that an Avocado test
is compatible with unittest.TestCase, and it can be run with compatible
test runners.
Signed-off-by: NCleber Rosa <crosa@redhat.com>

We don't implement all of unittest, but rather inherit from the TestCase class.
Let's also fix the references to the assert* methods.
Signed-off-by: NCleber Rosa <crosa@redhat.com>

The given example was using the old test module/class. Also, for clarity
sake, let's add the "new" import style for the Avocado Test class.
Signed-off-by: NCleber Rosa <crosa@redhat.com>

Including groupping together the "human" results and then "machine"
result formats in another subsection.

Changes from v1:
 * Wording suggestion: "on how to write a plugin" instead of "on how
   to write plugin"
Signed-off-by: NCleber Rosa <crosa@redhat.com>

We don't want users to care if some core feature is implemented as
a plugin. The important piece of information here is that Avocado
allows for its result to be written in different formats.
Signed-off-by: NCleber Rosa <crosa@redhat.com>

Besides updating the command outputs to match the current code, the
text was attempted to be made simpler and easier to follow.

Also, some sections were made subsections of the "Writing a plugin"
section.

Changes from v1:
 * Fix "lien" (instead of "line") typo
Signed-off-by: NCleber Rosa <crosa@redhat.com>

The output of the plugins command has changed. It now includes plugins
that may fail to load or even have been disabled (usually by themselves).

Let's make the user aware of these new possibilities and update the UI
examples.

Changes from v1:
 * Fix wording suggestion of "cleaner" instead of "clean"
Signed-off-by: NCleber Rosa <crosa@redhat.com>

Makefile: New `link_vt` and `link_virt` targets

Add a little more granularity to our Makefile. 'make link'
still works the way one would expect it to.
Signed-off-by: NLucas Meneghel Rodrigues <lmr@redhat.com>

Signed-off-by: NLucas Meneghel Rodrigues <lmr@redhat.com>

examples.tests: Add params descriptions

Summarize the test params to help people understand and run and
adjust test variants via multiplexer easily.
Signed-off-by: NLukáš Doktor <ldoktor@redhat.com>

  avocado.core.test: Remove the obsoleted "runTest" [v4]

The recent API reorganization made a module requiring
importlib to be loaded at setup stage. Hence the backport
python-importlib, available in EPEL, has to be added to
the BuildRequires field of the spec.
Signed-off-by: NLucas Meneghel Rodrigues <lmr@redhat.com>

The gendata is a nice example of multiple-subtests test. Add
a functional test that checks gendata creates the files
correctly and that two subtests are spawned.
Signed-off-by: NLukáš Doktor <ldoktor@redhat.com>

The runTest method has been obsoleted and everyone should be using
"test*" method(s) instead. This patch removes the support and replaces
the default and example entry points to "test".
Signed-off-by: NLukáš Doktor <ldoktor@redhat.com>

core.test: Map generic exceptions to TestError [v2]

The uid is only a test name and is not unique across the execution. We
should use tagged_name which consists of the uid and the optional tag to
be consistent with avocado runner.
Signed-off-by: NLukáš Doktor <ldoktor@redhat.com>

List all supported instrumented test statuses and add note about
BASH library to run instrumented tests.
Signed-off-by: NLukáš Doktor <ldoktor@redhat.com>

On unhandeled unknown exceptions the test should finish with ERROR
rather than FAIL as the test developer didn't think it might happen.

This behavior is configurable in config when the user have a different
opinion.
Signed-off-by: NLukáš Doktor <ldoktor@redhat.com>

avocado.core.loader: Discover only per-plugin-default tests [v2]

Loader plugins can specify default set of tests, when none supplied.
Currently list of these defaults is generated and then examined by
all loader plugins. This might generate clashes and false-negative
results, for example avocado-vt defines "vt_list_all" which obviously
shouldn't be parsed by file-plugin.

This patch changes the behavior so when no urls specified each plugin
chose and processes only his own defaults. To do this it was necessary
to reorder the recognition thus now you get all successful hits of all
urls from the first plugin, then the second....

Additionally small optimization was added to skip urls which are already
successfully assigned. This doesn't affects the results as they were
only added when not already handled.

Last minor tweak avoids false-positive result when exception occurs
during the "discover" phase as mapping is assigned after successful
discovery.
Signed-off-by: NLukáš Doktor <ldoktor@redhat.com>