From 169173248322a8f0814fd9d8e1c4663ecd9a4f1e Mon Sep 17 00:00:00 2001
From: Merlin Mathesius <merlinm@redhat.com>
Date: Sep 14 2017 18:58:17 +0000
Subject: Add detailed steps for running a set of package tests using this shim


---

diff --git a/README.rst b/README.rst
index a13f36a..b10490b 100644
--- a/README.rst
+++ b/README.rst
@@ -2,10 +2,10 @@
 task-standard-interface-shim
 ============================
 
-This task is meant to run new `standard interface tests<https://fedoraproject.org/wiki/Changes/InvokingTests>`_
+This task is meant to run new `standard interface tests <https://fedoraproject.org/wiki/Changes/InvokingTests>`_
 in Taskotron.
 
-For now, it uses the soon-to-be-legacy taskyaml but that will change as litaskotron
+For now, it uses the soon-to-be-legacy taskyaml but that will change as libtaskotron
 starts to support Ansible natively.
 
 Assumptions that are made:
@@ -22,3 +22,43 @@ Dependencies to run the task:
 To run the task, use something like::
 
   runtask -i <build> -t koji_build runtask.yml
+
+
+Detailed steps for running a set of package tests using this shim
+-----------------------------------------------------------------
+
+**Note**: Since running this shim manually will run the package test playbook
+locally in "classic" mode, you'll likely want to do so on a disposable VM
+that you "snapshot" just before running the tests so you can easily recover
+from whatever the tests may do to your local system!
+
+#. Install the ``libtaskotron`` package on your system::
+
+     $ sudo dnf install libtaskotron
+
+#. Clone *this* repo to your system and make it your current directory::
+
+     $ git clone https://pagure.io/taskotron/task-standard-interface-shim.git
+     $ cd task-standard-interface-shim
+
+#. Locate a recent Koji build for the package for which you want to run tests.
+
+   #. Browse to: http://koji.fedoraproject.org/koji/search?type=package&match=glob
+   #. Search for your package name. For example, "sed".
+   #. Identify the package build you want tested.
+      You'll want to pick one with a suffix that matches the OS release
+      of your test machine, and most likely the most recent build.
+      Make a note of that Koji build NVR.
+      For example, "sed-4.4-1.fc26".
+
+#. Use ``libtaskotron``'s ``runtask`` command to run the shim task, providing
+   it with the NVR of the Koji build identified in the previous step.
+   For example::
+
+     $ sudo runtask -i sed-4.4-1.fc26 -t koji_build runtask.yml
+
+#. That's it! The task will install the required packages for the standard
+   test interface and run the tests locally.
+   The last line of the output will tell you the location of the test
+   artifacts directory.
+   For example, ``/var/lib/taskotron/artifacts/20170914_182657_474165``.