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>

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>

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

When wrapping process, the parameter for a local wrap is defined
by using a shell-like glob interface (*make for example).

So remove the parts that mentions the old behavior (absolute
 and relative paths comparison), before the changes
introduced in commit f6bf2c02

Also, drop obvious and thus useless comment about the wrapper when
it's expressed as a relative path
Signed-off-by: NRudá Moura <rmoura@redhat.com>

We recently updated that representation.
Signed-off-by: NLucas Meneghel Rodrigues <lmr@redhat.com>

--mux-entry was a bit confusing as what it does it splits the result
params into multiple slices and while quering for keys they are
evaluated in the specified order, thus behaving the same as Linux PATH
bash variable.
Signed-off-by: NLukáš Doktor <ldoktor@redhat.com>

While still making the VERSION symbol available in the top level
Avocado module. Even though this is very simple information that
could live under the avocado module itself, it would break the
consistency of having avocado.core importing from avocado (toplevel).
Signed-off-by: NCleber Rosa <crosa@redhat.com>

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>

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>

APIs are the interfaces that our libraries provide. So where we actually
want to talk about the full set of value that we provide to test users,
let's use the term libraries. And use APIs when it makes more sense to
do so.
Signed-off-by: NCleber Rosa <crosa@redhat.com>

First, the wording was not clear about the language choices and the
added benefits of using Python. Also, let's focus on using the term
libraries instead of APIs. Libraries are an important part of Avocado
(see definition of what Avocado is) and IMHO denote more value than
the term APIs does.
Signed-off-by: NCleber Rosa <crosa@redhat.com>

And not *on* a given language.
Signed-off-by: NCleber Rosa <crosa@redhat.com>

This is just a review followed by minor wording changes and some
heavier formatting changes.

Changes from v1:
* Wording changes suggested by Lucas.
Signed-off-by: NCleber Rosa <crosa@redhat.com>

After reading the text and shuffling the order a bit, I think this
has an easier to follow structure. A few highlights:

* An Avocado test is really a method, that is, for many methods we
  have many tests.
* Suppress the attempt to briefly explain the Multiplexer here,
  giving instead a link to a more complete documentation.

Changes from v1:
* Mention the function naming conventions for the test methods and
  link to PEP 8 relevant section for functions and classes.
* Break into finer grained sections.
Signed-off-by: NCleber Rosa <crosa@redhat.com>

[fixup] docs: simplify Writing Avocado Test section text
Signed-off-by: NCleber Rosa <crosa@redhat.com>

The idea is to remove everything that is not critical to the user's
understanding of the core concepts.

Also, to sync to the new multi-test in a single class capabilities
of Avocado, let's name the main test method `test`. This paves the
way for other (multi test) examples that name test methods with
the exact same prefix (test_foo, test_bar and so on).
Signed-off-by: NCleber Rosa <crosa@redhat.com>

This includes moving the reference text and diagram on test order
resolution to the Reference Guide. Since this also included
information on what are simple and instrumented tests, let's
merge and reuse that.

Also, let's rename "Simple example" to "Basic example" so that it
does not confuse users with the concept of a Simple Test, since this
example is actually an Instrumented Test.
Signed-off-by: NCleber Rosa <crosa@redhat.com>

This commit tries to reduce the learning curve for a new Avocado user.

* The sections were broken down with new levels
* Reduce text by using links if users want more information on a topic
* Introduced a Reference Guide, where these more detailed and often
  design/internals about Avocado will be documented.
* Default the usage examples assuming an installation based on packages
* A lot of wording changes, always intending to make it simpler

Changes from v1:
* Wording changes suggested by Lucas.
Signed-off-by: NCleber Rosa <crosa@redhat.com>

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

First, let's assume these docs are intended for users by renaming
the first section simply "Installing Avocado".

I tried to make the "Installing Avocado" introductory text shorter,
so that it's easier to read, and if the user really wants to take
a look at the repos he/she can click on the links.

Also broke down the installation section into more sub levels.
Signed-off-by: NCleber Rosa <crosa@redhat.com>

This makes it even more clear that this feature is about a command
line option and can work with unmodified tests.

Also, the user reading this will at least know that some other
options are available, and will probably refer back to `--help`
if he needs further assistance.
Signed-off-by: NCleber Rosa <crosa@redhat.com>

Since the command line (aka transparent execution of binaries) use
case is easier to grasp and probably will see more frequent use then
the API, let's present that first.

Also, standardize on the feature names, fix some typos and add a
little bit more of cross reference.
Signed-off-by: NCleber Rosa <crosa@redhat.com>

Like a git commit message, let's try to be really succient about the
first line a user will read about avocado.
Signed-off-by: NCleber Rosa <crosa@redhat.com>

Since Avocado in our context is a proper name, and not really just
some fruit, let's refer to it using a capitalized word.
Signed-off-by: NCleber Rosa <crosa@redhat.com>

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>