diff --git a/.travis.yml b/.travis.yml
index 466e7046e41c4600709b215c72fb580c26c57b05..792ae8f17fe19012b96690c2e1f9fa25abbd51d3 100644
--- a/.travis.yml
+++ b/.travis.yml
@@ -29,7 +29,7 @@ dist: xenial
install:
- cd "$TRAVIS_BUILD_DIR"
- - sudo ./install_base_ubuntu.sh
+ - sudo ./install_base_ubuntu.sh --install-doc-extras
- echo "$(python3 --version)"
script:
diff --git a/doc/conf.py b/doc/conf.py
index ba697c06863adeed09d12b0d0f2e13950467b209..2af97de94e64be15fdc559fe7f61bb858b04a4cf 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -98,6 +98,8 @@ extensions = [
'sphinx.ext.coverage',
'sphinx.ext.imgmath',
'sphinx.ext.viewcode',
+ 'sphinx.ext.inheritance_diagram',
+ 'sphinxcontrib.plantuml',
]
# Add any paths that contain templates here, relative to this directory.
diff --git a/doc/kernel_tests.rst b/doc/kernel_tests.rst
index 8f8e636bc9d009610f7cc81ea2cc1794dad8ddec..c7ed538c12ec9975a666b46bd40892f0c4c91a28 100644
--- a/doc/kernel_tests.rst
+++ b/doc/kernel_tests.rst
@@ -69,8 +69,8 @@ See the usage example of :class:`~lisa.tests.base.TestBundle`
Writing tests
=============
-Basics
-++++++
+Concepts
+++++++++
Writing scheduler tests can be difficult, especially when you're
trying to make them work without relying on custom tracepoints (which is
@@ -94,7 +94,70 @@ Have a look at its documentation for implementation and usage examples.
A simple test implementation worth looking at is
:class:`~lisa.tests.scheduler.sanity.CapacitySanity`.
-Implementations of :class:`~lisa.tests.base.TestBundle` can
+The relationship between the test classes has been condensed into this diagram,
+although you'll find more details in the API documentation of these classes.
+
+.. uml::
+
+ class TestMetric {
+ + data
+ + units
+ }
+
+
+ note bottom of TestMetric {
+ TestMetrics serve to answer
+ "Why did my test fail/pass ?".
+ They are free-form, so they can be
+ error counts, durations, stats...
+ }
+
+ class Result {
+ PASSED
+ FAILED
+ UNDECIDED
+ }
+
+ class ResultBundle {
+ + result : Result
+ + add_metric()
+ }
+
+ ResultBundle "1" *- "1" Result
+ ' This forces a longer arrow ------------v
+ ResultBundle "1" *- "1..*" TestMetric : " "
+
+ class TestBundle {
+ # _from_target() : TestBundle
+ + from_target() : TestBundle
+ + from_dir() : TestBundle
+ }
+
+ note right of TestBundle {
+ Methods returning TestBundle
+ are alternative constructors
+
+ from_target() does some generic
+ work, then calls _from_target(). You'll
+ have to override it depending on what
+ you want to execute on the target.
+ }
+
+ class MyTestBundle {
+ # _from_target() : TestBundle
+ + test_foo_is_bar() : ResultBundle
+ }
+
+ note right of MyTestBundle {
+ Non-abstract TestBundle classes
+ must define test methods that return
+ a ResultBundle
+ }
+
+ TestBundle <|-- MyTestBundle
+ MyTestBundle .. ResultBundle
+
+Implementations of :class:`~lisa.tests.base.TestBundle._from_target` can
execute any sort of arbitry Python code. This means that you are free to
manipulate sysfs entries, or to execute arbitray binaries on the target. The
:class:`~lisa.wlgen.workload.Workload` class has been created to
@@ -109,8 +172,8 @@ tasks with a pre-determined utilization.
API
===
-Base API
-++++++++
+Base classes
+++++++++++++
.. automodule:: lisa.tests.base
:members:
@@ -123,11 +186,25 @@ Scheduler tests
EAS tests
---------
+
+.. inheritance-diagram:: lisa.tests.scheduler.eas_behaviour
+ :top-classes: lisa.tests.base.TestBundle
+ :parts: 1
+
+|
+
.. automodule:: lisa.tests.scheduler.eas_behaviour
:members:
Load tracking tests
-------------------
+
+.. inheritance-diagram:: lisa.tests.scheduler.load_tracking
+ :top-classes: lisa.tests.base.TestBundle
+ :parts: 1
+
+|
+
.. automodule:: lisa.tests.scheduler.load_tracking
:members:
:private-members: _from_target
@@ -135,23 +212,48 @@ Load tracking tests
Misfit tests
------------
+.. inheritance-diagram:: lisa.tests.scheduler.misfit
+ :top-classes: lisa.tests.base.TestBundle
+ :parts: 1
+
+|
+
.. automodule:: lisa.tests.scheduler.misfit
:members:
Sanity tests
------------
+.. inheritance-diagram:: lisa.tests.scheduler.sanity
+ :top-classes: lisa.tests.base.TestBundle
+ :parts: 1
+
+|
+
.. automodule:: lisa.tests.scheduler.sanity
:members:
Hotplug tests
+++++++++++++
+
+.. inheritance-diagram:: lisa.tests.hotplug.torture
+ :top-classes: lisa.tests.base.TestBundle
+ :parts: 1
+
+|
+
.. automodule:: lisa.tests.hotplug.torture
:members:
Cpufreq tests
+++++++++++++
+.. inheritance-diagram:: lisa.tests.cpufreq.sanity
+ :top-classes: lisa.tests.base.TestBundle
+ :parts: 1
+
+|
+
.. automodule:: lisa.tests.cpufreq.sanity
:members:
diff --git a/install_base_ubuntu.sh b/install_base_ubuntu.sh
index 637789bd322dd8ff6a39bf9a224d1a6a3dbbe183..6fcdda47a3355102a9def8fc41891845ceb0cc44 100755
--- a/install_base_ubuntu.sh
+++ b/install_base_ubuntu.sh
@@ -10,7 +10,7 @@ SCRIPT_DIR=$(dirname "${BASH_SOURCE[0]}")
cd "$SCRIPT_DIR"
usage() {
- echo Usage: "$0" [--install-android-sdk]
+ echo Usage: "$0" [--install-android-sdk] [--install-doc-extras]
}
latest_version() {
@@ -59,13 +59,20 @@ install_nodejs() {
apt-get install -y nodejs npm
}
+install_doc_extras() {
+ apt-get -y install plantuml graphviz
+}
+
set -eu
install_android_sdk=n
+install_doc_extras=n
for arg in "$@"; do
if [ "$arg" == "--install-android-sdk" ]; then
- install_android_sdk=y
+ install_android_sdk=y
+ elif [ "$arg" == "--install-doc-extras" ]; then
+ install_doc_extras=y
else
echo "Unrecognised argument: $arg"
usage
@@ -87,6 +94,10 @@ if [ "$install_android_sdk" == y ]; then
install_sdk
fi
+if [ "$install_doc_extras" == y ]; then
+ install_doc_extras
+fi
+
# Make sure we exit with no errors, so we can start making use of that
# if we introduce some meaningful error handling. Since some packages are not
# needed for some tasks and since we don't have mechanisms in place to group
diff --git a/lisa/tests/base.py b/lisa/tests/base.py
index f16a219d616067a6cf6c9ad689fcfdc5494f9af1..5d8e10033e303dd5efc70f466bca1c10a449866f 100644
--- a/lisa/tests/base.py
+++ b/lisa/tests/base.py
@@ -194,10 +194,10 @@ class TestBundle(Serializable, abc.ABC):
a :class:`TestBundle`.
* :attr:`VERIFY_SERIALIZATION` is there to ensure both above methods remain
operationnal at all times.
- * `res_dir` parameter of `__init__` must be stored as an attribute
+ * ``res_dir`` parameter of ``__init__`` must be stored as an attribute
without further processing, in order to support result directory
relocation.
- * Test methodes should have a return annotation for the
+ * Test methods should have a return annotation for the
:class:`ResultBundle` to be picked up by the test runners.
**Implementation example**::
@@ -348,7 +348,7 @@ class TestBundle(Serializable, abc.ABC):
"""
super().to_path(self._filepath(res_dir))
-class RTATestBundle(TestBundle, abc.ABC):
+class RTATestBundle(TestBundle):
"""
"Abstract" class for :class:`lisa.wlgen.rta.RTA`-powered TestBundles
diff --git a/lisa/tests/hotplug/torture.py b/lisa/tests/hotplug/torture.py
index 74f0966322de72eb42274b7a1fb5bbaded63eeed..e8bb6e7b17d2f0546e0a8b8f2a3b498ce60b91e1 100644
--- a/lisa/tests/hotplug/torture.py
+++ b/lisa/tests/hotplug/torture.py
@@ -33,7 +33,7 @@ from lisa.utils import ArtifactPath
class CPUHPSequenceError(Exception):
pass
-class HotplugBase(TestBundle, abc.ABC):
+class HotplugBase(TestBundle):
def __init__(self, plat_info, target_alive, hotpluggable_cpus, live_cpus):
res_dir = None
super().__init__(res_dir, plat_info)
diff --git a/lisa/tests/scheduler/eas_behaviour.py b/lisa/tests/scheduler/eas_behaviour.py
index 00241183caf8799ddc5f9d75a145b95459c20580..3970ddcbc6bac084d91de7a4540cdb6cae6e879c 100644
--- a/lisa/tests/scheduler/eas_behaviour.py
+++ b/lisa/tests/scheduler/eas_behaviour.py
@@ -36,7 +36,7 @@ from lisa.trace import requires_events
from lisa.target import Target
from lisa.trace import FtraceCollector
-class EASBehaviour(RTATestBundle, abc.ABC):
+class EASBehaviour(RTATestBundle):
"""
Abstract class for EAS behavioural testing.
diff --git a/setup.py b/setup.py
index cb1178d3037ae6ef76dc4e1777ed5e3ec7be8e06..b9c67637d64c18202a8221f0d859697d00210de7 100755
--- a/setup.py
+++ b/setup.py
@@ -114,7 +114,8 @@ setup(
"doc": [
"sphinx >= 1.8",
- "sphinx_rtd_theme"
+ "sphinx_rtd_theme",
+ "sphinxcontrib-plantuml",
],
"test": [