Improved examples in docs; full example with test; fixed fixture id

Signed-off-by: Andreas Maier <andreas.r.maier@gmx.de>

Makefile

@@ -209,6 +209,7 @@ py_src_files := \
     $(wildcard $(test_dir)/*/*.py) \
     $(wildcard $(test_dir)/*/*/*.py) \
     $(wildcard $(test_dir)/*/*/*/*.py) \
+		$(wildcard examples/*.py) \
 
 ifdef TESTCASES
   pytest_opts := $(TESTOPTS) -k $(TESTCASES)
@@ -558,11 +559,11 @@ safety_$(python_pymn_version).done: develop_reqs_$(python_pymn_version).done Mak
 test: develop
 ifeq ($(python_mn_version),3.4)
 	@echo "Makefile: Running unit tests (without coverage)"
-	pytest --color=yes $(pytest_warning_opts) $(pytest_opts) $(test_dir)/unittest -s --es-file $(test_dir)/unittest/es_server.yml
+	pytest --color=yes $(pytest_warning_opts) $(pytest_opts) $(test_dir)/unittest examples -s --es-file $(test_dir)/unittest/es_server.yml
 	@echo "Makefile: Done running unit tests (without coverage)"
 else
 	@echo "Makefile: Running unit tests (with coverage)"
-	coverage run --source=$(package_name) --rcfile=.coveragerc -m pytest --color=yes $(pytest_warning_opts) $(pytest_opts) $(test_dir)/unittest -s --es-file $(test_dir)/unittest/es_server.yml
+	coverage run --source=$(package_name) --rcfile=.coveragerc -m pytest --color=yes $(pytest_warning_opts) $(pytest_opts) $(test_dir)/unittest examples -s --es-file $(test_dir)/unittest/es_server.yml
 	coverage report --rcfile=.coveragerc
 	@echo "Makefile: Done running unit tests (with coverage)"
 endif

docs/usage.rst

@@ -92,7 +92,8 @@ to the details for accessing the server:
         Example Pytest test function that tests something.
 
         Parameters:
-          es_server (Server): Server to be used for the test
+          es_server (easy_server.Server): Pytest fixture; the server to be
+            used for the test
         """
 
         # Standard properties from the server file:
@@ -107,25 +108,35 @@ to the details for accessing the server:
         username = es_server.secrets['username']
         password = es_server.secrets['password']
 
-        # Log on to the host and perform some test
-        . . .
+        # Session to server using a fictitious session class
+        session = MySession(host, username, password)
+
+        # Test something
+        result = my_session.perform_function()
+        assert ...
+
+        # Cleanup
+        session.close()
 
 The example shows how to access the standard and user-defined properties
-from the server file for demonstration purposes. The data structure
+from the "easy-server" file for demonstration purposes. The data structure
 of the user-defined properties in the server file and of the secrets
 in the vault file is completely up to you, so you could decide to have the host
 and userid in user-defined properties in the server file, and have
 only the password in the vault file.
 
 The ``es_server`` parameter of the test function is a
 :class:`easy_server:easy_server.Server` object that represents a
-server item from the server file for testing against a single server.
+server item from the server file for testing against a single server. It
+includes the corresponding secrets item from the vault file.
 
 An example server file that provides the user-defined properties
 used in the test function shown above would be:
 
 .. code-block:: yaml
 
+    vault_file: vault.yml
+
     servers:
 
       myserver1:                            # Nickname of the server
@@ -247,12 +258,16 @@ In a file ``session_fixture.py``:
         Pytest fixture representing the set of MySession objects to use for
         testing against a server.
         """
+        # Session to server using a fictitious session class
         session = MySession(
-            host = es_server.secrets['host']
-            username = es_server.secrets['username']
-            password = es_server.secrets['password']
+            host=es_server.secrets['host']
+            username=es_server.secrets['username']
+            password=es_server.secrets['password']
         )
+
         yield session
+
+        # Cleanup
         session.close()
 
 In your test functions, you can now use that fixture:
@@ -263,4 +278,24 @@ In your test functions, you can now use that fixture:
     from session_fixture import my_session
 
     def test_sample(my_session):
+        """
+        Example Pytest test function that tests something.
+
+        Parameters:
+          my_session (MySession): Pytest fixture; the session to the server
+            to be used for the test
+        """
         result = my_session.perform_function()  # Test something
+
+A side note: Pylint and Flake8 do not recognize that 'es_server' and 'my_session'
+are fixtures that are interpreted by Pytest and thus complain about the unused
+'es_server' and 'my_session' names, and about the 'my_session' parameter that
+hides the global name. The following markup silences these tools:
+
+.. code-block:: python
+
+    # pylint: disable=unused-import
+    from pytest_easy_server import es_server  # noqa: F401
+    from session_fixture import my_session  # noqa: F401
+
+    def test_sample(my_session):  # pylint: disable=redefined-outer-name

examples/test_function.py

@@ -2,27 +2,56 @@
 Example pytest test function for pytest-easy-server project.
 """
 
-from pytest_easy_server import es_server
+# pylint: disable=unused-import
+from pytest_easy_server import es_server  # noqa: F401
 
-def test_sample(es_server):
+
+class MySession(object):
+    """Fictitious session class with dummy methods"""
+
+    def __init__(self, host, username, password):
+        """Open session with the server"""
+        print("\nMySession: host={}, username={}, password={}".
+              format(host, username, password))
+
+    @staticmethod
+    def perform_function():
+        """Perform some function on the server"""
+        return 42
+
+    @staticmethod
+    def close():
+        """Close session with the server"""
+        pass
+
+
+def test_sample(es_server):  # pylint: disable=redefined-outer-name
     """
     Example Pytest test function that tests something.
 
     Parameters:
-      es_server (easy_server.Server): Server to be used.
+      es_server (easy_server.Server): Pytest fixture; the server to be
+        used for the test
     """
 
     # Standard properties from the server file:
-    nickname = es_server.nickname
-    description = es_server.description
+    # nickname = es_server.nickname
+    # description = es_server.description
 
     # User-defined additional properties from the server file:
-    stuff = es_server.user_defined['stuff']
+    # stuff = es_server.user_defined['stuff']
 
     # User-defined secrets from the vault file:
     host = es_server.secrets['host']
     username = es_server.secrets['username']
     password = es_server.secrets['password']
 
-    # Log on to the host and perform some test
-    # . . .
+    # Session to server using a fictitious session class
+    session = MySession(host, username, password)
+
+    # Test something
+    result = session.perform_function()
+    assert result == 42
+
+    # Cleanup
+    session.close()

pytest_easy_server/plugin.py

@@ -71,7 +71,7 @@ def fixtureid_es_server(fixture_value):
     """
     es_obj = fixture_value
     assert isinstance(es_obj, easy_server.Server)
-    return "easy_server={0}".format(es_obj.nickname)
+    return "es_server={0}".format(es_obj.nickname)
 
 
 def pytest_generate_tests(metafunc):