Merge branch '1.4.5.2' into dev

docs/installation.rst

@@ -69,8 +69,8 @@ Python environment.
 
 .. Note::
 
-On some linux flavors, you may need to run
-``sudo apt-get install libmysqlclient-dev`` prior to bin/install-reqs.
+    On some linux flavors, you may need to run
+    ``sudo apt-get install libmysqlclient-dev`` prior to bin/install-reqs.
 
 Installing the dependencies requires `pip`_ 1.0 or higher. `pip`_ is
 automatically available in a `virtualenv`_; if not using `virtualenv`_ you may

docs/userguide/howto.rst

@@ -19,21 +19,7 @@ on the fields in that screen.
 
 Steps
 ^^^^^
-    #. navigate to ``Manage | Versions``
-    #. click the "create a version" button
-    #. set the product to the product in question
-    #. specify the version to copy Environments and Cases from.  In our case,
-       this will be ``1.0``
-    #. type in the name of the new Version.  In our case: ``2.0``
-    #. codename is optional.
-    #. click the "save productversion" button
-
-Result
-^^^^^^
-Now you will have a new product version, and a new ``2.0`` version of each test
-case.  If you change the ``2.0`` version of a case, the ``1.0`` version remains
-unchanged.  This is so that the steps in your test can evolve as your product
-does without changing the tests that applied to earlier versions.
+See Tutorial: :ref:`New Version<new-product-version>`
 
 
 Fill in test cases missing from one Product Version into another
@@ -98,22 +84,7 @@ will need to clone the 1.0 test runs to 2.0 and update them.
 
 Steps
 ^^^^^
-    #. navigate to ``Manage | Runs``
-    #. find the test run you want to use in 2.0
-    #. click the clone button for that run
-    #. The new run will have the name "Cloned: foo" and be in DRAFT mode
-    #. edit the newly cloned run.  **Note:** It must be in DRAFT mode to change
-       the product version field.
-    #. Update the name as you wish
-    #. change the Product Version field to the new version 2.0:
-        * |product_version|
-    #. save as status active, or...
-    #. activate the new run with the status drop-down.
-
-Result
-^^^^^^
-Now you will have a new run that applies to your new product version ``2.0``
-that is ready to be executed.
+See Tutorial: :ref:`Migrate Runs<migrate-runs>`
 
 
 Get a link to a result of a test just after submitting it
@@ -140,6 +111,4 @@ that other users have submitted for the same case in that environment.
 .. |case_result| image:: img/case_result.png
     :height: 40px
 
-.. |product_version| image:: img/product_version.png
-    :height: 40px
 

docs/userguide/index.rst

@@ -4,7 +4,7 @@ User's Guide
 This guide provides documentation of how to use MozTrap as well as some of
 its underlying concepts and design decisions.
 
-**New to using MozTrap?**  See the :ref:`Getting Started Guide <getting-started>`
+**New to using MozTrap?**  See the :ref:`Tutorial <tutorial>`
 for an overview of some basic tasks to get you rolling.
 
 If you find an issue with MozTrap, please enter a bug in `Bugzilla`_
@@ -14,7 +14,7 @@ If you find an issue with MozTrap, please enter a bug in `Bugzilla`_
 .. toctree::
    :maxdepth: 3
 
-   gettingstarted
+   tutorial/index
    howto
    faq
    model/products

docs/userguide/model/execution.rst

@@ -28,8 +28,14 @@ The test case steps executed in test runs may be different for each Product
 Version, as the Product itself evolves. See :ref:`Test Cases <test-cases>` for
 more info on how test case versions relate to Product Versions.
 
-An active test run can be disabled, which halts all execution of tests in that
-run until it is made active again.
+.. _test-run-states:
+
+Draft test runs cannot be executed yet.  This is a good state if you're still
+working on it and aren't ready for people to see it.  It won't show up in the
+list of test runs for your product in the ``Run Tests`` section.
+
+An active test run can be disabled or made draft, which halts all
+execution of tests in that run until it is made active again.
 
 .. _test-run-series:
 

docs/userguide/tutorial/create_cases.rst

@@ -0,0 +1,96 @@
+.. _tutorial-create-tests:
+
+MozTrap Tutorial, part 2
+========================
+
+In this section, we discuss creating test cases and organizing them into
+suites.
+
+Create test Suites
+------------------
+
+Test Suites are collections of test cases.  A test case can belong to more
+than one suite, if need be.
+
+Let's write some tests to cover two areas of the **SpeckDetector**.  It should
+detect specks of sand and specks of pollen.  And you should also be able to
+update your SpeckDetector's firmware.
+
+Steps
+^^^^^
+    #. navigate to ``manage | suites``
+    #. click ``create a test suite``
+    #. set your product to ``SpeckDetector``
+    #. set name to ``Specks``
+    #. enter a description that includes Markdown_ syntax::
+
+        PRECONDITIONS
+        =============
+        * Must have some specks
+
+        LINKS
+        =====
+        * [Specks of Life](http://example.com/)
+
+    #. you won't have any available cases yet, so skip that and just
+       click ``save suite``
+    #. repeat these steps for a suite but name it ``Firmware``
+
+Create test Cases
+-----------------
+
+Now we need to create some test cases for those suites.
+
+Steps
+^^^^^
+    #. navigate to ``manage | cases``
+    #. click ``create a test case``
+    #. set your product to ``SpeckDetector``
+    #. set version to ``1.0``
+    #. set suite to ``Specks``
+    #. :ref:`ID Prefix<test-case-edit-fields>` is optional, skip it for now
+    #. set name to ``Detect a pollen speck``
+    #. for ``instruction`` 1, enter::
+
+        hold detector held away from pollen
+
+    #. for ``expected`` 1, enter::
+
+        no detection lights
+
+    #. tab to ``instruction`` 2, enter::
+
+        hold detector above a pollen speck
+
+    #. tab to ``expected`` 2, enter::
+
+        detector lights up word "pollen"
+
+    #. click ``save test case``
+
+
+That's one down.  Whew!  OK, now create another test case for the ``firmware``
+suite with steps like this:
+
+    #. name: ``update firmware``
+    #. for ``instruction`` 1, enter::
+
+        navigate to firmware update screen and select "update"
+
+    #. for ``expected`` 1, enter::
+
+        see "a firmware update is available"
+
+    #. tab to ``instruction`` 2, enter::
+
+        click "apply update"
+
+    #. tab to ``expected`` 2, enter::
+
+        firmware value should say the new version
+
+
+Great!  You're done with your cases!
+
+.. _Markdown: http://daringfireball.net/projects/markdown/syntax
+

docs/userguide/gettingstarted.rst → docs/userguide/tutorial/create_product.rst

@@ -1,21 +1,14 @@
-.. _getting-started:
+.. _tutorial-create-product:
 
-Getting Started Guide
-=====================
-
-If you're new to MozTrap and would like a general walk-though of how to get
-initial data setup and start testing your product, this is your guide.
-
-
-Setup a new product in a new system
------------------------------------
+MozTrap Tutorial, part 1
+========================
 
 The following is a description of how to setup your new system to test your
-product.
+product.  Part 1 will focus on setting up your Product and Environments.
 
 
-Create environments
-^^^^^^^^^^^^^^^^^^^
+Setup Environments
+------------------
 
 Odds are you will be testing your product in several
 :ref:`environments<environments>`.  These could be a collection of hardware
@@ -35,20 +28,31 @@ steps:
     #. navigate to ``manage | environments``
         * |manage_environments|
     #. click ``create a profile``
-    #. give your profile a name
-    #. Depending on your setup, you may have several
-       :ref:`environment elements<environment-elements>` in your system already.
-    #. If you see a category that applies to your product already, then expand
-       It to choose the elements that apply.  If not, then click |add_category|
-       to create a new one
-    #. Within a category, if you don't see the correct element, then create
-       one by typing in the field |add_element| and hitting enter
-    #. Once you have all the categories and elements checked that you want to
-       test, click ``save profile``
-
-This will create a matrix list of all possible combinations of the environment
-elements you chose.  However, it may be true that you don't want to test ALL
-combinations.  If that's the case, then you can winnow down the list to test.
+    #. give your profile the name ``Speck Envs``
+    #. .. note::
+
+           Depending on your setup, you may have several
+           :ref:`environment elements<environment-elements>` in your system already.
+
+           If you see a category that applies to your product already, then expand
+           It to choose the elements that apply.  If not, then click |add_category|
+           to create a new one
+    #. In our case, we'll need to create everything, so click |add_category|
+       and type ``location`` and hit enter
+    #. in the category, find the field that says |add_element| and type
+       ``laboratory`` and hit "enter"
+    #. add another element called ``field`` and hit enter
+    #. make sure to check the ``location`` category and all its elements
+    #. click ``save profile``
+
+.. note::
+
+    This will create a matrix list of all possible combinations of the
+    environment elements for each category you chose.  In our case it's very
+    simple (only 2).  However, for other products, you may have several
+    categories.  It may be true that you don't want to test ALL combinations
+    that were created.  If that's the case, then you can winnow down the list
+    to test.
 
 To winnow down the list of environments to test:
 
@@ -58,9 +62,10 @@ To winnow down the list of environments to test:
 
 
 Create a Product
-^^^^^^^^^^^^^^^^
+----------------
 
-For this example, we will presume your product is called **SpeckDetector**.
+Now that you have your environment profile setup, let's create your product.
+We will presume your product is called **SpeckDetector**.
 It detects specks.  Very handy.
 
     #. navigate to ``manage | products``:
@@ -85,13 +90,3 @@ It detects specks.  Very handy.
 .. |edit_icon| image:: img/edit_icon.png
     :height: 20px
 
-
-Create some tests in an existing system
----------------------------------------
-
-In progress...
-
-Run some tests in an existing system
-------------------------------------
-
-In progress...

docs/userguide/tutorial/create_runs.rst

@@ -0,0 +1,72 @@
+.. _tutorial-create-runs:
+
+Moztrap Tutorial, part 3
+========================
+
+In this section, we use the pieces you've already built to create and activate
+a test run that users can execute.
+
+
+Create a Test Run
+-----------------
+
+Test Runs are made up of test suites and are specific to a version of your
+product.  You may want to have several test runs.  One could be called
+``smoke`` and another ``feature complete`` and yet another
+``full functional tests``.  Or you could break them up into larger functional
+areas like ``front-end`` and ``server``.
+
+Let's create your first **SpeckDetector** test run.  It will contain all the
+suites you have created so far.  Let's call this ``feature complete``.
+
+Steps
+^^^^^
+    #. navigate to ``manage | runs``
+    #. click ``create a test run``
+    #. set your product version to ``SpeckDetector 1.0``
+    #. set name to ``feature complete``
+    #. enter a description that includes Markdown_ syntax.  This information
+       will be displayed at the top of each page while running the tests::
+
+        LINKS
+        =====
+        * [Specks of Life](http://example.com/)
+        * [Bugzilla](http://bugzilla.mycompany.com)
+
+    #. :ref:`series<test-run-series>` defaults to true.  We will want to run
+       our tests against several ongoing builds of the **SpeckDetector**, so
+       in our case we *will* create a series.  Please take a moment to see
+       what a :ref:`run series<test-run-series>` is.
+    #. Leave the ``start`` date as today.  If you want the run to expire, then
+       set the ``end`` date, too.
+    #. drag both suites from ``available`` to ``included``
+    #. click ``save run``
+
+
+Activate your Run
+-----------------
+
+Your run is just about ready.  However, there's one more critical step you
+must take before it can be executed.  You must make the run *active*.
+
+Why not have test runs active all the time?  Good question.
+:ref:`Look here<test-run-states>`, Curious George.
+
+Steps
+^^^^^
+    #. navigate to ``manage | runs``
+    #. find your test run ``feature complete``
+    #. click the status icon
+        * |run_activate|
+    #. click "Activate"
+
+.. |run_activate| image:: img/run_activate.png
+    :height: 150px
+
+
+Isn't this exciting?  You now have a test run series created and ready to go!
+Go tell your boss.
+
+
+.. _Markdown: http://daringfireball.net/projects/markdown/syntax
+