From c3ffa4e492407fbdc6d5efdfba0c080b0d6da6e4 Mon Sep 17 00:00:00 2001 From: Zack Cerza Date: Thu, 9 Jun 2016 15:05:12 -0600 Subject: [PATCH] Add intro for testers Signed-off-by: Zack Cerza --- docs/README.rst | 3 +++ docs/index.rst | 1 + docs/intro_testers.rst | 61 ++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 65 insertions(+) create mode 100644 docs/intro_testers.rst diff --git a/docs/README.rst b/docs/README.rst index a1fb3c65b8..dc4a00abfc 100644 --- a/docs/README.rst +++ b/docs/README.rst @@ -23,6 +23,9 @@ operations on remote hosts over SSH, as implemented by `Paramiko When testing, it is common to group many `jobs` together to form a `test run`. +If you are new to teuthology and simply want to run existing tests, check out +:ref:`intro_testers` + Provided Utilities ================== diff --git a/docs/index.rst b/docs/index.rst index d01f6be13a..4a8b110ef8 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -5,6 +5,7 @@ Content Index :maxdepth: 2 README.rst + intro_testers.rst siteconfig.rst openstack_backend.rst INSTALL.rst diff --git a/docs/intro_testers.rst b/docs/intro_testers.rst new file mode 100644 index 0000000000..d4f328936c --- /dev/null +++ b/docs/intro_testers.rst @@ -0,0 +1,61 @@ +.. _intro_testers: + +======================== +Introduction for Testers +======================== + +This document is aimed at providing an introduction to running existing test suites. + +We assume here that you have access to an operational test lab; if not, ask +your local admin for access! + +If you're here to test upstream Ceph, start `here +`__. + + +Terminology +=========== + +In the abstract, each set of tests is defined by a `suite`. All of our suites +live in the `ceph-qa-suite repository +`__, in the `suites` subdirectory. + +In concrete terms, a `run` is what is created by assembling the contents of a +`suite` into a number of `jobs`. A `job` is created by assembling a number of +`fragments` (also known as `facets`) together. Each `fragment` is in `YAML +`__ format. + +Each `job` definition contains a list of `tasks` to execute, along with +`roles`. `Roles` tell `teuthology` how many nodes to use for each `job` along +with what functions each node will perform. + +To go into more depth regarding suite design, see `ceph-qa-suite`'s `README`. + +One example of this is the `smoke +`__ suite. + + +Scheduling +========== +Most testing happens by scheduling `runs`. The way we do that is using the +`teuthology-suite` command. + +To get a preview of what `teuthology-suite` might do, try:: + + teuthology-suite -v -s smoke -c master -m mira --dry-run + +Assuming a build is available, that should pretend to schedule several jobs. If +it complains about missing packages, try swapping `master` with `jewel` or one +of the other Ceph stable branches. + +To see even more detail, swap `-v` with `-vv`. It will print out each job +definition in full. To limit the number of jobs scheduled, you may want to use +the `--limit`, `--filter`, or `--filter-out` flags. + +To actually schedule, drop `--dry-run` and optionally use the `--email` flag to +get an email when the test run completes. + +`teuthology-suite` also prints out a link to the run in `pulpito +`__ that will display the current status of +each job. The Sepia lab's pulpito instance is `here +`__. -- 2.39.5