Re: [PATCH 2/4] lnst.RecipeCommon.PacketAssert: add documentation

[Ondrej Lichtner]

So the Tests.PacketAssert class and also the PacketAssert class are not
linked into anywhere and doesn't even show up in the modules index.

I think for "lnst.Tests" we should create a new subsection "Test
modules" inside the "tester api" where we can describe the base test
module and link in the specific ones that we support.

You don't need to create the base test module documentation, but can you
at least create the document hierarchy and link in the PacketAssert test
module into it?

For lnst.RecipeCommon I'm undecided for now. I think for that some
"Other supported packages" top level section may be interesting just as
a temporary space until we think of a good way to organize this.

-Ondrej

On Wed, Sep 30, 2020 at 04:14:50PM +0200, jurbanov(a)redhat.com wrote:
>  From: Jozef Urbanovsky <jurbanov(a)redhat.com&gt;
>  
>  Signed-off-by: Jozef Urbanovsky <jurbanov(a)redhat.com&gt;
>  ---
>   lnst/RecipeCommon/PacketAssert.py | 27 +++++++++++++++++++++++++++
>   lnst/Tests/PacketAssert.py        | 20 ++++++++++++++++++++
>   2 files changed, 47 insertions(+)
>  
>  diff --git a/lnst/RecipeCommon/PacketAssert.py b/lnst/RecipeCommon/PacketAssert.py
>  index 689250e..b42be74 100644
>  --- a/lnst/RecipeCommon/PacketAssert.py
>  +++ b/lnst/RecipeCommon/PacketAssert.py
>  @@ -4,6 +4,17 @@ from lnst.Tests import PacketAssert
>   from lnst.Common.LnstError import LnstError
>   
>   class PacketAssertConf(object):
>  +    """
>  +    Class for the configuration of the :any:`PacketAssert` class
>  +
>  +    :param host: client in :any:`PingConf` object used to specify host for the ping
> test
>  +    :param iface: interface used for the ping test
>  +    :param p_filter: string representation of desired packets in dump
>  +    :param grep_for: string representation of the content of given packet in dump
>  +    :param p_min: minimum count of the packets to be found in the dump
>  +    :param p_max: maximum count of the packets to be found in the dump
>  +    :param promiscuous: toggle of promiscuous mode
>  +    """
>       def __init__(self, host, iface, **kwargs):
>           self._host = host
>           self._iface = iface
>  @@ -42,9 +53,19 @@ class PacketAssertConf(object):
>           return self._promiscuous
>   
>   class PacketAssertTestAndEvaluate(BaseRecipe):
>  +    """
>  +    Class to control and execute :any:`PacketAssert` test.
>  +    """
>       started_job = None
>   
>       def packet_assert_test_start(self, packet_assert_config):
>  +        """
>  +        Method starts a :any:`PacketAssert` job and stores ***started_job*** attribute
>  +        containing LNST :any:`Job: object.
>  +
>  +        :param packet_assert_config: configuration in a form of :any:`PacketAssertConf`
>  +        class
>  +        """
>           if self.started_job:
>               raise LnstError("Only 1 packet_assert job is allowed to run at a
> time.")
>   
>  @@ -54,6 +75,12 @@ class PacketAssertTestAndEvaluate(BaseRecipe):
>           self.started_job = host.prepare_job(packet_assert).start(bg=True)
>   
>       def packet_assert_test_stop(self):
>  +        """
>  +        Method kills a process executing :any:`PacketAssert` job and
>  +        resets the value of the ***started_job*** attribute.
>  +
>  +        :return: result of the packet assert
>  +        """
>           if not self.started_job:
>               raise LnstError("No packet_assert job is running.")
>   
>  diff --git a/lnst/Tests/PacketAssert.py b/lnst/Tests/PacketAssert.py
>  index 25a92ba..901fdc0 100644
>  --- a/lnst/Tests/PacketAssert.py
>  +++ b/lnst/Tests/PacketAssert.py
>  @@ -8,6 +8,19 @@ from lnst.Tests.BaseTestModule import BaseTestModule
>   from lnst.Common.LnstError import LnstError
>   
>   class PacketAssert(BaseTestModule):
>  +    """
>  +    Class to control tcpdump test
>  +
>  +    This class runs tcpdump and searches through its output in order
>  +    to evaluate whether specified packets are traversing the network stack.
>  +
>  +    :param interface: interface used for the :any:`PacketAssert` test
>  +    :param p_filter: string representation of desired packets in dump
>  +    :param grep_for: string representation of the content of given packet in dump
>  +    :param promiscuous: toggle of promiscuous mode
>  +    :param grep_exprs: concatenated expression to be used by grep for search
>  +    :param p_recv: amount of received packets
>  +    """
>       interface = DeviceParam(mandatory=True)
>       p_filter = StrParam(default='')
>       grep_for = ListParam(default=[])
>  @@ -57,6 +70,13 @@ class PacketAssert(BaseTestModule):
>           return False
>   
>       def run(self):
>  +        """
>  +        Method used for the control of :any:`PacketAssert` test.
>  +        Process with tcpdump is spawned and its output is digested
>  +        in order to find and count specified packets through grep expressions.
>  +
>  +        :return: result of the run
>  +        """
>           self._res_data = {}
>           if not is_installed("tcpdump"):
>               self._res_data["msg"] = "tcpdump is not installed on this
> machine!"
>  -- 
>  2.25.4
>  _______________________________________________
>  LNST-developers mailing list -- lnst-developers(a)lists.fedorahosted.org
>  To unsubscribe send an email to lnst-developers-leave(a)lists.fedorahosted.org
>  Fedora Code of Conduct: https://docs.fedoraproject.org/en-US/project/code-of-conduct/
>  List Guidelines: https://fedoraproject.org/wiki/Mailing_list_guidelines
>  List Archives:
> https://lists.fedorahosted.org/archives/list/[e-mail]...