os-autoinst image:https://api.travis-ci.org/os-autoinst/os-autoinst.svg?branch=master[link=https://travis-ci.org/os-autoinst/os-autoinst] image:https://coveralls.io/repos/github/os-autoinst/os-autoinst/badge.svg?branch=master[link=https://coveralls.io/github/os-autoinst/os-autoinst?branch=master]
=========================================================================================================================================================================================================================================================================================================
:author: openSUSE Team at SUSE
:toc:

The OS-autoinst project aims at providing a means to run fully
automated tests.  Especially to run tests of basic and low-level
operating system components such as bootloader, kernel, installer and
upgrade, which can not easily and safely be tested with other
automated testing frameworks.  However, it can just as well be used to
test firefox and openoffice operation on top of a newly installed OS.

os-autoinst can be executed alone, but is currently designed to be
executed together with openQA, the web user interface that allows to
run more than one os-autoinst instance at the same time.

More information on os-autoinst and openQA can be found on
http://os-autoinst.github.io/openQA/

Getting started
---------------

To install os-autoinst, you can see link:INSTALL.asciidoc[INSTALL]

To execute an instance of os-autoinst, we need to create file named
vars.json, that we use to store the values of the different variables
that will configure and drive the behavior of the application.

There are some variables used by os-autoinst itself and other that are
used by the tests.  A minimal vars.json file can be:

[source, javascript]
-------------------------------------------------------------------
{
   "DISTRI" :      "opensuse",
   "CASEDIR" :     "/full/path/for/tests",
   "NAME" :        "test-name",
   "ISO" :         "/full/path/for/iso",
   "VNC" :         "91",
   "BACKEND" :     "qemu",
   "DESKTOP" :     "kde"
}
-------------------------------------------------------------------

Be advised that the file vars.json is read and also written by isotovideo so
make sure to backup handcrafted versions of this file.

Now we can launch the application with:

$ ../os-autoinst/isotovideo

and we can use VNC to connect to the QEMU instance:

$ vncviewer localhost:91 -ViewOnly -Shared

How to contribute
-----------------

If you want to contribute to this project, please clone and send
git-pull requests via https://github.com/os-autoinst/os-autoinst.

More information on the contribution can be found on
http://os-autoinst.github.io/openQA/contact/, too.

Issues are tracked on https://progress.opensuse.org/projects/openqav3/ and
also on https://github.com/os-autoinst/os-autoinst/issues

Rules for commits
^^^^^^^^^^^^^^^^^

* Every commit is checked by https://travis-ci.org/travis[Travis CI] as soon as
you create a pull request but you *should* run the os-autoinst tests locally,
i.e. call
----
./autogen.sh
./configure
make
----
once to setup your workspace and before every commit
----
make check
----

* You *may* also run local tests on your machine or in your own development
environment to verify everything works as expected.

* For git commit messages use the rules stated on
http://chris.beams.io/posts/git-commit/[How to Write a Git Commit Message] as
a reference

* Every pull request is reviewed in a peer review to give feedback on possible
implications and how we can help each other to improve

If this is too much hassle for you feel free to provide incomplete pull
requests for consideration or create an issue with a code change proposal.
