Sure, sphix gave us a hand with the generation of the index file to
point us to the right direction. But, by now, we don't have to keep
that old tip.
Signed-off-by: NCleber Rosa <crosa@redhat.com>

For completeness purporses this adds the current year to the copyright
string.
Signed-off-by: NCleber Rosa <crosa@redhat.com>

As it was done in the man pages a while ago, it's probably better to
just refer to the Avocado Team as the author of the documentation as a
whole.
Signed-off-by: NCleber Rosa <crosa@redhat.com>

Only avocado.Test is of general interest to test writers. For that reason
the entire test module has been moved to the avocado.core namespace.

The recommended way to go about writing instrumented tests is something like:

   from avocado import Test
   class MyTest(Test):
      def test_foo(self):
         do_stuff()

Changes from v2:
* Fixed references in docstrings
* Fixed refrences of avocado.test in Writing Test Guide docs

Changes from v1:
* Fixed comment typo on commit message
* Fixed old reference of avocado.test (then test.Test) instead of
  avocado then Test in GDB docs.
Signed-off-by: NCleber Rosa <crosa@redhat.com>

This patch changes the default mux-entry to `/run` as it tends to be
more convenient.

The biggest change is that this location is used as default location
for added YAML files. It's also used as the base when using relative
path YAML file injection. The only way to include file into the exact
location is to use absolute path (`/your/location`).

The benefit is that single simple YAML file doesn't require any additional
location and is in the default mux-entry location. Check the documentation
for details.
Signed-off-by: NLukáš Doktor <ldoktor@redhat.com>

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

We forgot to update all places where the params API
was referenced, leaving us with old constructs in code
samples, such as referring to a params key by
self.params.key.
Signed-off-by: NLucas Meneghel Rodrigues <lmr@redhat.com>

Signed-off-by: NRudá Moura <rmoura@redhat.com>

This patch adds documentation of the "new params API" and removes the
compatility layer. From now on only the API with paths is valid:

    self.params.get(key, path='*', default=None)

where the default path '*' matches anything from --mux-entry path.
Default path is `/test`.
Signed-off-by: NLukáš Doktor <ldoktor@redhat.com>

This patch modifies all example tests to use the new API. It uses the
default path, which is `*`, which matches the mux-entry paths ONLY.
In order to get the values it's necessarily to inject the YAML files
into the mux-entry path, by default `/test`, eg:

    avocado run sleeptest -m /test:examples/tests/sleeptest.py.data/
    sleeptest.yaml

It might seen as a bit more complicated to execute, but it's definitely
easier for maintaining and combining existing YAML files. To execute
matrix of tests you simply inject them into 2 different `/test` children,
eg: `-m /test/by_length:lengths.yaml /test/by_method:methods.yaml`.
Signed-off-by: NLukáš Doktor <ldoktor@redhat.com>

Add section inside "Development Tips" to include a graph
of module dependencies.
Signed-off-by: NRudá Moura <rmoura@redhat.com>

In the documentation, explain that the test API is everything
under avocado module, but excludes avocado.core.

Also, Avocado works with plugins, so let's talk about it,
in the introduction too.
Signed-off-by: NRudá Moura <rmoura@redhat.com>

Move avocado.plugins to avocado.core.plugins, in conformance to our
purpose of keeping things not related to test developers,
inside avocado.core, isolated from users.
Signed-off-by: NRudá Moura <rmoura@redhat.com>

Move avocado.core.data_dir to avocado.data_dir so that test
developers can make use of it.
Signed-off-by: NRudá Moura <rmoura@redhat.com>

Move avocado.result to avocado.core.result, in conformance to
our purpose of keeping things not related to test developers,
inside avocado.core, isolated from users.
Signed-off-by: NRudá Moura <rmoura@redhat.com>

Export avocado.core.job.main as avocado.main, so that make it look
like an API for test developers to use.
Signed-off-by: NRudá Moura <rmoura@redhat.com>

Move avocado.job to avocado.core.job, in conformance to our
purpose of keeping things not related to test developers,
inside avocado.core, isolated from users.
Signed-off-by: NRudá Moura <rmoura@redhat.com>

Commit 120345aa attempted to download and build avocado-virt API
documentation together with the avocado API. While this was reliable
offline, it succeeded only on the very first version builds at
readthedocs.org.

So, let's revert back that hackish form of combining the docs. Further
commits will add API documentation generation to avocado-virt itself,
and link avocado and avocado-virt by means of the intersphinx mapping
feature and readthedocs.org sub-project support.
Signed-off-by: NCleber Rosa <crosa@redhat.com>

It was attempted to fill in the gaps so that avocado-virt would be
able to transparently use avocado GDB support. It turns out that a
number of foundation changes will have to be made to support launching
process in the background while running inside GDB.

So, for now, let's document that limitation.
Signed-off-by: NCleber Rosa <crosa@redhat.com>

The default UI has changed a bit, so let's update the documentation to
match it.
Signed-off-by: NCleber Rosa <crosa@redhat.com>

Remove words for setup, cleanup and action and update to the new slang:
setUp, tearDown and runTest.
Signed-off-by: NRudá Moura <rmoura@redhat.com>

This patch will checkout the avocado-virt repo during the documentation
build, so that all of avocado's API (including -virt) is presented at a
single and comprehensive location.
Signed-off-by: NCleber Rosa <crosa@redhat.com>

This patch is initial support for people using custom bash scripts
with avocado. Tests should use:

    PATH=$(avocado "exec-path"):$PATH

and then they can utilize the helpers.

This version contain functions to write to Test.log the same way it's
possible from python including failing the test with TestWarn in case
avocado_warn was used.
Signed-off-by: NLukáš Doktor <ldoktor@redhat.com>

From the current command line `--disable-output-check` replace it
with the new command line `--output-check {on,off}`, defaults to `on`.

Use `--output-check=off` to behave like ``--disable-output-check`.

Also, validate the value from command line `--output-check-record`.
Signed-off-by: NRudá Moura <rmoura@redhat.com>

The current way the text was built looks bad while
looking at the docs in the browser.
Signed-off-by: NLucas Meneghel Rodrigues <lmr@redhat.com>

This patch simplifies the concept of WARN test. In case user uses the
self.log.warn or self.log.warning methods, test is marked as dirty and
in case everything else worked fine it finishes with TestWarn exception.
Signed-off-by: NLukáš Doktor <ldoktor@redhat.com>

Signed-off-by: NLukáš Doktor <ldoktor@redhat.com>

This example demonstrate simple usage of GDB API.
Signed-off-by: NLukáš Doktor <ldoktor@redhat.com>

Even though internally we have some more descendants of avocado.test.Test, to
a user, AFAICT, only instrumented and simple tests are available.
Signed-off-by: NCleber Rosa <crosa@redhat.com>

It's obviously not true that Avocado only allows to run tests on "your laptop".
Also let's keep the running of tests and the outcome all in the present tense.
Signed-off-by: NCleber Rosa <crosa@redhat.com>

Signed-off-by: NCleber Rosa <crosa@redhat.com>

Add a new section inside the "Getting started guide", about installing Avocado
from the git repository with confidence that the dependences will be installed.
Signed-off-by: NRudá Moura <rmoura@redhat.com>

Add link to the DevConf mindmap to introduction documentation.
Signed-off-by: NLukáš Doktor <ldoktor@redhat.com>

Some typos found during automated inspection of the code.
Signed-off-by: NLucas Meneghel Rodrigues <lmr@redhat.com>

The reasons for the proposed move include:

1) Even though find_command() looks for executables, it doesn't really
   try to execute them as a living process.

2) The implementation looks for it in a $PATH like list, so, out of a
   possibly better choice, avocado.utils.path was chosen.

3) Other modules can use that functionality, but not the execution of
   process.

4) Avoid circular dependencies: this is actually the first motivation
   of the proposed change, and a true story with the GDB plugin/test.
   Since avocado.utils.process depends on avocado.gdb, this module
   can not use find_command() to look for gdb/gdbserver binaries.
Signed-off-by: NCleber Rosa <crosa@redhat.com>

As far as I can see and test, the directory doesn't have to be present in the
repository, as it'll be created on-the-fly during the documentation generation.

As a bonus, avoid a dangerous "rm -rf $(VARIABLE)/*" in make clean (which is a
pattern for catastrophic results -- if $VARIABLE, whatever it is, is not set,
this will result in "rm -rf /*").

It might not be obvious how merging multiple yaml files work. Here is a
simple explanation.
Signed-off-by: NLukáš Doktor <ldoktor@redhat.com>

Instead of detecting non-sibling nodes generate list of leaves per
each parent and pass it up the tree to the root. Results should be
the same as before, only speed is improved.

Additionally allow specifying nodes (!join), whose children belongs to
the same group. This extends the possibilities beyond what was possible
before.
Signed-off-by: NLukáš Doktor <ldoktor@redhat.com>

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

Add support to inspect and find tests inside a directory, recursively,
by using the method `discover_url`. It takes a url (path) and
returns the tests parameters it discovers.

The loader object has the .discover() method, that can be used
to inspect the location, and the .validate() method, that will
discover any problems on the user's input.

We are also changing the behavior of avocado to error out on
invalid inputs (missing paths or files that are not avocado
tests). Therefore, the concept of MISSING or NOT_A_TEST both
disappear from the UI. Unittests were updated to reflect the
new status quo.
Signed-off-by: NRudá Moura <rmoura@redhat.com>
Signed-off-by: NLucas Meneghel Rodrigues <lmr@redhat.com>