{"action":"created","comment":{"url":"https://api.github.com/repos/SatelliteQE/testimony/pulls/comments/70463421","id":70463421,"diff_hunk":"@@ -1,159 +1,346 @@\n Testimony\n =========\n \n-An approach to document test cases in the Python source code\n-------------------------------------------------------------\n+.. contents:: Topics\n \n-Are you tired of managing your test cases in a test case management tool and\n-your test code in a Python automation framework?  Testimony can help you to use\n-your Python automation framework as a test case repository tool.\n+.. _what_is_testimony:\n \n-The project Testimony is written to inspect and report on the Python test\n-cases.  There are several reporting features in this program.\n+What is Testimony?\n+``````````````````\n \n-Testimony allows you to configure:\n+Testimony is an approach to document the test cases in the Python source code\n+using the function docstrings.\n+\n+If your answer is ``yes`` to both the questions below, then ``Testimony`` is a\n+right tool for you.\n+\n+1. Are you using python to automate your test cases?\n+2. Are you tired of managing your test cases in a test case management tool?\n+   \n+Don't worry.  Testimony can help you to use your Python automation framework as\n+a test case repository tool.\n+\n+.. _advantages:\n+\n+Advantages\n+``````````\n+\n+Using Testimony brings lot of advantages to your project:\n+\n+1. Avoid using a test case management tool to document test cases by leveraging\n+   function docstrings for the same.\n+2. Enforce standard for your test case docstrings.\n+3. Run with CI tools like Travis to validate your code after every check-in.\n+4. Save a lot of time from the conventional way of writing test cases using a\n+   test management tool.\n+5. Easily extract test case information using Testimony and port it to any test\n+   management tool.\n+\n+.. _testcase_docstring_format:\n+\n+Test Case Docstring format\n+``````````````````````````\n+\n+Testimony allows you to easily configure ``Testimony tokens`` which are the\n+defined docstring items which will be used in test case parsing.\n \n 1. tokens - Allowed values to be used as docstring items in your tests.  Default\n    tokens are ``assert``, ``bz``, ``feature``, ``setup``, ``status``, ``steps``,\n    ``tags``, ``test`` and ``type``.\n 2. minimum-tokens - minimum set of tokens that are needed for each of your\n    tests.  Default minimum tokens are ``assert``, ``feature`` and ``test``.\n \n-In a test case docstring, every token should be prefixed with ``@`` and\n-suffixed with ``:``. This will ensure that Testimony provides right reports.\n-The reports supported by testimony are:\n+.. note::\n \n-1. print - prints all captured tests with the parsed tokens for each test. Also\n-   it prints non-recognized tokens.\n-2. summary - presents a summary of all tests with useful information like:\n-   number of tests missing docstring, number of tests corresponding to each\n-   defined token, and total number of test cases.\n-3. validate - helps ensure that all your tests atleast have the minimal set\n-   of tokens defined.  The information presented by this command will help you\n-   identify the issues pertaining to each test.  A non-zero return code will be\n-   returned when:\n+  To help test case parsing, make sure that each test case docstring has the\n+  tokens prefixed with ``@`` and suffixed with ``:``.  Otherwise, you may see\n+  incorrect results.\n \n-     - minimal set of tokens is not present for atleast 1 test case\n-     - one or more tests is missing the docstring\n-     - An unexpected token identified\n+.. _sample_testcase:\n \n-Advantages\n-----------\n-1. Avoids using a test case management tool to document test cases by reusing\n-   the Python automation framework.\n-2. Enforces test cases to follow a defined standard.\n-3. Runs in integration with tools like Travis to get a report as and when you\n-   check in the code.\n-4. Saves a lot of time from the conventional way of writing test cases using a\n-   test management tool.\n-5. The test case information can be easily extracted from Testimony and can be\n-   ported to any test management tool.\n+Sample Test Case\n+++++++++++++++++\n+\n+A sample python test case with test case tokens is shown below:\n \n-Test lookup and definition\n---------------------------\n+.. code-block:: python\n \n-The ``PATH`` argument of testimony accepts more than one value.  Testimony\n-captures all python test modules (``.py`` files whose names start with\n-``test_``) in the given paths. If ``PATH`` is a directory, then the directory\n-and its subdirectories will be considered as well.\n+    def test_login_1(self):\n+        \"\"\"Check if a user is able to login with valid userid and password\n \n-Inside a test module, Testimony looks for functions whose names start with\n-``test_``.  It then parses the function docstrings and extracts the tokens.\n-Also it creates namespaces for module and class level docstrings which will\n-then be reused in the children tests. For example, if a module has a token\n-called ``feature``, then all tests in that module will inherit it by default.\n-But the individual tests can choose to override this value by defining their\n-own.  The token lookup will happen in the following order and it will stop on\n-the very first match::\n+        More description for the test.\n \n- 1. function level\n- 2. class level\n- 3. module level\n+        @feature: Login\n+        @setup: Navigate to abc.com\n+        @steps:\n+            1. Launch the url\n+            2. Log in with valid user credentials\n+        @assert: Log in successful\n+        @bz: 1234567\n+        @automated: false\n+        \"\"\"\n \n-A sample docstring will look like the following::\n+In the above example, as you may guess - `feature`, `setup`, `steps`, `assert`,\n+`bz`, `automated` are all tokens.\n \n-    \"\"\"Test to check log in as a valid user\n+.. _how_it_works:\n \n-    More description for the test.\n+How it works?\n+`````````````\n \n-    @feature: Login\n+To understand how Testimony works, let's look at the ``help`` command:\n \n-    @setup: Navigate to abc.com\n+.. code-block:: bash\n \n-    @steps:\n+    $ testimony --help\n+      Usage: testimony [OPTIONS] REPORT [PATH]...\n \n-    1. Launch the url\n-    2. Log in with valid user credentials\n+      Inspect and report on the Python test cases.\n \n-    @assert: Log in successful\n+      Options:\n+      -j, --json             JSON output\n+      -n, --nocolor          Color output\n+      --tokens TEXT          Comma separated list of expected tokens\n+      --minimum-tokens TEXT  Comma separated list of minimum expected tokens\n+      --help                 Show this message and exit.\n \n-    @bz: 1234567\n+Testimony does the following to parse the test case docstrings:\n \n-    @automated: false\n-    \"\"\"\n+1. It captures all `Python Test modules`_ in the path(s) provided by ``PATH``\n+   argument.\n \n-Considering that the above docstring was defined on a test in a module\n-``tests/test_login.py``, a print report will output something like::\n+     - As the definition implies, ``PATH`` accepts more than one value.\n+     - If ``PATH`` is a directory, then the directory and its subdirectories\n+       will be inspected for test modules as well.\n \n-    tests/test_login.py\n-    ===================\n+2. Inside each identified test module, it looks for `Python Test case\n+   functions`_\n+3. It then parses the function docstrings and extracts the tokens. Also it","path":"docs/index.rst","position":185,"original_position":185,"commit_id":"d4dded2127e823d77cd2488b9f75a7aa1747bce0","original_commit_id":"d4dded2127e823d77cd2488b9f75a7aa1747bce0","user":{"login":"omaciel","id":53362,"avatar_url":"https://avatars.githubusercontent.com/u/53362?v=3","gravatar_id":"","url":"https://api.github.com/users/omaciel","html_url":"https://github.com/omaciel","followers_url":"https://api.github.com/users/omaciel/followers","following_url":"https://api.github.com/users/omaciel/following{/other_user}","gists_url":"https://api.github.com/users/omaciel/gists{/gist_id}","starred_url":"https://api.github.com/users/omaciel/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/omaciel/subscriptions","organizations_url":"https://api.github.com/users/omaciel/orgs","repos_url":"https://api.github.com/users/omaciel/repos","events_url":"https://api.github.com/users/omaciel/events{/privacy}","received_events_url":"https://api.github.com/users/omaciel/received_events","type":"User","site_admin":false},"body":"* s/extracts the/extracts their?\r\n* s/Also/Also,","created_at":"2016-07-12T15:34:02Z","updated_at":"2016-07-12T15:34:02Z","html_url":"https://github.com/SatelliteQE/testimony/pull/109#discussion_r70463421","pull_request_url":"https://api.github.com/repos/SatelliteQE/testimony/pulls/109","_links":{"self":{"href":"https://api.github.com/repos/SatelliteQE/testimony/pulls/comments/70463421"},"html":{"href":"https://github.com/SatelliteQE/testimony/pull/109#discussion_r70463421"},"pull_request":{"href":"https://api.github.com/repos/SatelliteQE/testimony/pulls/109"}}},"pull_request":{"url":"https://api.github.com/repos/SatelliteQE/testimony/pulls/109","id":77124956,"html_url":"https://github.com/SatelliteQE/testimony/pull/109","diff_url":"https://github.com/SatelliteQE/testimony/pull/109.diff","patch_url":"https://github.com/SatelliteQE/testimony/pull/109.patch","issue_url":"https://api.github.com/repos/SatelliteQE/testimony/issues/109","number":109,"state":"open","locked":false,"title":"Update documentation","user":{"login":"sthirugn","id":3309189,"avatar_url":"https://avatars.githubusercontent.com/u/3309189?v=3","gravatar_id":"","url":"https://api.github.com/users/sthirugn","html_url":"https://github.com/sthirugn","followers_url":"https://api.github.com/users/sthirugn/followers","following_url":"https://api.github.com/users/sthirugn/following{/other_user}","gists_url":"https://api.github.com/users/sthirugn/gists{/gist_id}","starred_url":"https://api.github.com/users/sthirugn/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/sthirugn/subscriptions","organizations_url":"https://api.github.com/users/sthirugn/orgs","repos_url":"https://api.github.com/users/sthirugn/repos","events_url":"https://api.github.com/users/sthirugn/events{/privacy}","received_events_url":"https://api.github.com/users/sthirugn/received_events","type":"User","site_admin":false},"body":"","created_at":"2016-07-12T14:00:16Z","updated_at":"2016-07-12T15:34:02Z","closed_at":null,"merged_at":null,"merge_commit_sha":"3778f70f9edb2c49d0deb9bf29a5c7c1625db42b","assignee":null,"assignees":[],"milestone":null,"commits_url":"https://api.github.com/repos/SatelliteQE/testimony/pulls/109/commits","review_comments_url":"https://api.github.com/repos/SatelliteQE/testimony/pulls/109/comments","review_comment_url":"https://api.github.com/repos/SatelliteQE/testimony/pulls/comments{/number}","comments_url":"https://api.github.com/repos/SatelliteQE/testimony/issues/109/comments","statuses_url":"https://api.github.com/repos/SatelliteQE/testimony/statuses/d4dded2127e823d77cd2488b9f75a7aa1747bce0","head":{"label":"sthirugn:doc-update","ref":"doc-update","sha":"d4dded2127e823d77cd2488b9f75a7aa1747bce0","user":{"login":"sthirugn","id":3309189,"avatar_url":"https://avatars.githubusercontent.com/u/3309189?v=3","gravatar_id":"","url":"https://api.github.com/users/sthirugn","html_url":"https://github.com/sthirugn","followers_url":"https://api.github.com/users/sthirugn/followers","following_url":"https://api.github.com/users/sthirugn/following{/other_user}","gists_url":"https://api.github.com/users/sthirugn/gists{/gist_id}","starred_url":"https://api.github.com/users/sthirugn/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/sthirugn/subscriptions","organizations_url":"https://api.github.com/users/sthirugn/orgs","repos_url":"https://api.github.com/users/sthirugn/repos","events_url":"https://api.github.com/users/sthirugn/events{/privacy}","received_events_url":"https://api.github.com/users/sthirugn/received_events","type":"User","site_admin":false},"repo":{"id":29918530,"name":"testimony","full_name":"sthirugn/testimony","owner":{"login":"sthirugn","id":3309189,"avatar_url":"https://avatars.githubusercontent.com/u/3309189?v=3","gravatar_id":"","url":"https://api.github.com/users/sthirugn","html_url":"https://github.com/sthirugn","followers_url":"https://api.github.com/users/sthirugn/followers","following_url":"https://api.github.com/users/sthirugn/following{/other_user}","gists_url":"https://api.github.com/users/sthirugn/gists{/gist_id}","starred_url":"https://api.github.com/users/sthirugn/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/sthirugn/subscriptions","organizations_url":"https://api.github.com/users/sthirugn/orgs","repos_url":"https://api.github.com/users/sthirugn/repos","events_url":"https://api.github.com/users/sthirugn/events{/privacy}","received_events_url":"https://api.github.com/users/sthirugn/received_events","type":"User","site_admin":false},"private":false,"html_url":"https://github.com/sthirugn/testimony","description":"Inspect and Report python test cases using test case docstrings","fork":true,"url":"https://api.github.com/repos/sthirugn/testimony","forks_url":"https://api.github.com/repos/sthirugn/testimony/forks","keys_url":"https://api.github.com/repos/sthirugn/testimony/keys{/key_id}","collaborators_url":"https://api.github.com/repos/sthirugn/testimony/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/sthirugn/testimony/teams","hooks_url":"https://api.github.com/repos/sthirugn/testimony/hooks","issue_events_url":"https://api.github.com/repos/sthirugn/testimony/issues/events{/number}","events_url":"https://api.github.com/repos/sthirugn/testimony/events","assignees_url":"https://api.github.com/repos/sthirugn/testimony/assignees{/user}","branches_url":"https://api.github.com/repos/sthirugn/testimony/branches{/branch}","tags_url":"https://api.github.com/repos/sthirugn/testimony/tags","blobs_url":"https://api.github.com/repos/sthirugn/testimony/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/sthirugn/testimony/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/sthirugn/testimony/git/refs{/sha}","trees_url":"https://api.github.com/repos/sthirugn/testimony/git/trees{/sha}","statuses_url":"https://api.github.com/repos/sthirugn/testimony/statuses/{sha}","languages_url":"https://api.github.com/repos/sthirugn/testimony/languages","stargazers_url":"https://api.github.com/repos/sthirugn/testimony/stargazers","contributors_url":"https://api.github.com/repos/sthirugn/testimony/contributors","subscribers_url":"https://api.github.com/repos/sthirugn/testimony/subscribers","subscription_url":"https://api.github.com/repos/sthirugn/testimony/subscription","commits_url":"https://api.github.com/repos/sthirugn/testimony/commits{/sha}","git_commits_url":"https://api.github.com/repos/sthirugn/testimony/git/commits{/sha}","comments_url":"https://api.github.com/repos/sthirugn/testimony/comments{/number}","issue_comment_url":"https://api.github.com/repos/sthirugn/testimony/issues/comments{/number}","contents_url":"https://api.github.com/repos/sthirugn/testimony/contents/{+path}","compare_url":"https://api.github.com/repos/sthirugn/testimony/compare/{base}...{head}","merges_url":"https://api.github.com/repos/sthirugn/testimony/merges","archive_url":"https://api.github.com/repos/sthirugn/testimony/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/sthirugn/testimony/downloads","issues_url":"https://api.github.com/repos/sthirugn/testimony/issues{/number}","pulls_url":"https://api.github.com/repos/sthirugn/testimony/pulls{/number}","milestones_url":"https://api.github.com/repos/sthirugn/testimony/milestones{/number}","notifications_url":"https://api.github.com/repos/sthirugn/testimony/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/sthirugn/testimony/labels{/name}","releases_url":"https://api.github.com/repos/sthirugn/testimony/releases{/id}","deployments_url":"https://api.github.com/repos/sthirugn/testimony/deployments","created_at":"2015-01-27T14:50:38Z","updated_at":"2016-01-11T21:18:07Z","pushed_at":"2016-07-12T15:27:30Z","git_url":"git://github.com/sthirugn/testimony.git","ssh_url":"git@github.com:sthirugn/testimony.git","clone_url":"https://github.com/sthirugn/testimony.git","svn_url":"https://github.com/sthirugn/testimony","homepage":"","size":147,"stargazers_count":0,"watchers_count":0,"language":"Python","has_issues":false,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":0,"mirror_url":null,"open_issues_count":0,"forks":0,"open_issues":0,"watchers":0,"default_branch":"master"}},"base":{"label":"SatelliteQE:master","ref":"master","sha":"ccb86cd730e5f49dd08c9e7616c0066a4aacac8c","user":{"login":"SatelliteQE","id":8754276,"avatar_url":"https://avatars.githubusercontent.com/u/8754276?v=3","gravatar_id":"","url":"https://api.github.com/users/SatelliteQE","html_url":"https://github.com/SatelliteQE","followers_url":"https://api.github.com/users/SatelliteQE/followers","following_url":"https://api.github.com/users/SatelliteQE/following{/other_user}","gists_url":"https://api.github.com/users/SatelliteQE/gists{/gist_id}","starred_url":"https://api.github.com/users/SatelliteQE/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/SatelliteQE/subscriptions","organizations_url":"https://api.github.com/users/SatelliteQE/orgs","repos_url":"https://api.github.com/users/SatelliteQE/repos","events_url":"https://api.github.com/users/SatelliteQE/events{/privacy}","received_events_url":"https://api.github.com/users/SatelliteQE/received_events","type":"Organization","site_admin":false},"repo":{"id":16013320,"name":"testimony","full_name":"SatelliteQE/testimony","owner":{"login":"SatelliteQE","id":8754276,"avatar_url":"https://avatars.githubusercontent.com/u/8754276?v=3","gravatar_id":"","url":"https://api.github.com/users/SatelliteQE","html_url":"https://github.com/SatelliteQE","followers_url":"https://api.github.com/users/SatelliteQE/followers","following_url":"https://api.github.com/users/SatelliteQE/following{/other_user}","gists_url":"https://api.github.com/users/SatelliteQE/gists{/gist_id}","starred_url":"https://api.github.com/users/SatelliteQE/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/SatelliteQE/subscriptions","organizations_url":"https://api.github.com/users/SatelliteQE/orgs","repos_url":"https://api.github.com/users/SatelliteQE/repos","events_url":"https://api.github.com/users/SatelliteQE/events{/privacy}","received_events_url":"https://api.github.com/users/SatelliteQE/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/SatelliteQE/testimony","description":"Inspect and Report python test cases using test case docstrings","fork":false,"url":"https://api.github.com/repos/SatelliteQE/testimony","forks_url":"https://api.github.com/repos/SatelliteQE/testimony/forks","keys_url":"https://api.github.com/repos/SatelliteQE/testimony/keys{/key_id}","collaborators_url":"https://api.github.com/repos/SatelliteQE/testimony/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/SatelliteQE/testimony/teams","hooks_url":"https://api.github.com/repos/SatelliteQE/testimony/hooks","issue_events_url":"https://api.github.com/repos/SatelliteQE/testimony/issues/events{/number}","events_url":"https://api.github.com/repos/SatelliteQE/testimony/events","assignees_url":"https://api.github.com/repos/SatelliteQE/testimony/assignees{/user}","branches_url":"https://api.github.com/repos/SatelliteQE/testimony/branches{/branch}","tags_url":"https://api.github.com/repos/SatelliteQE/testimony/tags","blobs_url":"https://api.github.com/repos/SatelliteQE/testimony/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/SatelliteQE/testimony/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/SatelliteQE/testimony/git/refs{/sha}","trees_url":"https://api.github.com/repos/SatelliteQE/testimony/git/trees{/sha}","statuses_url":"https://api.github.com/repos/SatelliteQE/testimony/statuses/{sha}","languages_url":"https://api.github.com/repos/SatelliteQE/testimony/languages","stargazers_url":"https://api.github.com/repos/SatelliteQE/testimony/stargazers","contributors_url":"https://api.github.com/repos/SatelliteQE/testimony/contributors","subscribers_url":"https://api.github.com/repos/SatelliteQE/testimony/subscribers","subscription_url":"https://api.github.com/repos/SatelliteQE/testimony/subscription","commits_url":"https://api.github.com/repos/SatelliteQE/testimony/commits{/sha}","git_commits_url":"https://api.github.com/repos/SatelliteQE/testimony/git/commits{/sha}","comments_url":"https://api.github.com/repos/SatelliteQE/testimony/comments{/number}","issue_comment_url":"https://api.github.com/repos/SatelliteQE/testimony/issues/comments{/number}","contents_url":"https://api.github.com/repos/SatelliteQE/testimony/contents/{+path}","compare_url":"https://api.github.com/repos/SatelliteQE/testimony/compare/{base}...{head}","merges_url":"https://api.github.com/repos/SatelliteQE/testimony/merges","archive_url":"https://api.github.com/repos/SatelliteQE/testimony/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/SatelliteQE/testimony/downloads","issues_url":"https://api.github.com/repos/SatelliteQE/testimony/issues{/number}","pulls_url":"https://api.github.com/repos/SatelliteQE/testimony/pulls{/number}","milestones_url":"https://api.github.com/repos/SatelliteQE/testimony/milestones{/number}","notifications_url":"https://api.github.com/repos/SatelliteQE/testimony/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/SatelliteQE/testimony/labels{/name}","releases_url":"https://api.github.com/repos/SatelliteQE/testimony/releases{/id}","deployments_url":"https://api.github.com/repos/SatelliteQE/testimony/deployments","created_at":"2014-01-17T22:16:41Z","updated_at":"2016-01-14T12:14:27Z","pushed_at":"2016-07-12T15:27:31Z","git_url":"git://github.com/SatelliteQE/testimony.git","ssh_url":"git@github.com:SatelliteQE/testimony.git","clone_url":"https://github.com/SatelliteQE/testimony.git","svn_url":"https://github.com/SatelliteQE/testimony","homepage":"","size":160,"stargazers_count":7,"watchers_count":7,"language":"Python","has_issues":true,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":9,"mirror_url":null,"open_issues_count":11,"forks":9,"open_issues":11,"watchers":7,"default_branch":"master"}},"_links":{"self":{"href":"https://api.github.com/repos/SatelliteQE/testimony/pulls/109"},"html":{"href":"https://github.com/SatelliteQE/testimony/pull/109"},"issue":{"href":"https://api.github.com/repos/SatelliteQE/testimony/issues/109"},"comments":{"href":"https://api.github.com/repos/SatelliteQE/testimony/issues/109/comments"},"review_comments":{"href":"https://api.github.com/repos/SatelliteQE/testimony/pulls/109/comments"},"review_comment":{"href":"https://api.github.com/repos/SatelliteQE/testimony/pulls/comments{/number}"},"commits":{"href":"https://api.github.com/repos/SatelliteQE/testimony/pulls/109/commits"},"statuses":{"href":"https://api.github.com/repos/SatelliteQE/testimony/statuses/d4dded2127e823d77cd2488b9f75a7aa1747bce0"}}}}
{"actor":{"display_login":"omaciel"}}