From db8572796de8dd6245754cdc5974f4e7211efb04 Mon Sep 17 00:00:00 2001 From: Matthew Treinish Date: Fri, 17 Oct 2014 20:44:52 -0400 Subject: [PATCH] Add section on the basic data model This commit adds a section to the docs tree about the data model used in subunit2sql. Change-Id: I3a18f99c9800921abb500ab10d9f2090f182f6c3 --- doc/source/data_model.rst | 63 +++++++++++++++++++++++++++++++++++++++ doc/source/index.rst | 1 + 2 files changed, 64 insertions(+) create mode 100644 doc/source/data_model.rst diff --git a/doc/source/data_model.rst b/doc/source/data_model.rst new file mode 100644 index 0000000..6f93995 --- /dev/null +++ b/doc/source/data_model.rst @@ -0,0 +1,63 @@ +========================== +The subunit2sql Data Model +========================== + +The subunit2sql data model consists of 3 basic data types: runs, tests, and +test_runs. Each of these 3 types have an associated key value pair metadata table to store arbitrary metadata about any specific row. + +Runs +---- +Runs represent an individual test run, or in other words, a complete subunit +stream. They are used to track how many streams have been stored in the db and +high level information about them + +Properties: + +* **passes**: The total number of successful tests in the run. +* **fails**: The total number of failed tests during the run. +* **skips**: The total number of skipped tests during the run. +* **run_time**: The sum of the duration of executed tests during the run. Note, + this is not the time it necessarily took for the run to finish. For + example, the time for setUpClass and tearDownClass (assuming the + stream is from a python unittest run) would not be factored in. (as + they aren't stored in the subunit stream) Also, if the tests are + being run in parallel since this is just a raw sum this is not + factored in. +* **artifacts**: An optional link to where the logs or any other artifacts from + the run are stored. +* **run_at**: The time at which the run was stored in the DB. + +Tests +----- +Tests are the higher level grouping of unique tests across all runs. They are +used to aggregate the information about an individual tests from all the runs +stored in the db. + +Properties: + +* **test_id**: This would be normally be considered the test name, it is the id + used in the subunit stream for an individual test +* **success**: The total number of times this test has been run successfully +* **failure**: The total number of times this test has failed +* **run_count**: The total number of times this test has been executed + (obviously this excludes skips) it should be the sum of the success and + failure columns +* **run_time**: The moving average of the total duration of each test execution + + + +Test Runs +--------- +Test runs represent the individual execution of a test as part of run. They are +used for recording all the information about a single test's run. + +Properties: + +* **test_id**: The uuid representing the test which was run +* **run_id**: The uuid representing the run this was part of +* **status**: The outcome of the test. The valid values here are: + exists, xfail, unxsuccess, success, fail, skip. You can refer to + the `testtools documentation `_ + for the details on each status. +* **start_time**: The timestamp when test execution started +* **stop_time**: The timestamp when the test finished executing diff --git a/doc/source/index.rst b/doc/source/index.rst index 8b823ef..32b990c 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -8,6 +8,7 @@ Contents: :maxdepth: 2 README + data_model api