andy-maier / pytest-easy-server Goto Github PK

• Readme/Index/Intro: number of servers: "one or more"
• Readme/Intro: "references some vault": the vault uses the nicknames

See pytest-dev/pytest#8468

The master branch currently has the plugin enabled and reports low coverage.
PR #17 has the registration of the plugin disabled as well as the test case using the fixture and reports high coverage.

to either "Version M.N.U" or just "M.N.U".

The following is a just comments on the documentation.

1. I had real questions when I saw the name ...-tars and could not figure out where the tars came from until reading section 1.1. I don't have a better name right now but I suggest putting the definitiion of tars right at the top of the documentation.
   Andy: DONE - updated paragraph on index page and used that in intro section and on README.

2. First sentence. This package is going to be difficult to explain in any case unless someone has actually used the whole thing before. However, the lead to the documentation should be clear that:
   a. This is a pytest plugin
   b. It provides package for flexible definition of servers and groups of servers (Is this servers or ore generally targets including servers) that allows test definition against all or selected parts of the defined servers.
   c. You need something more in that leading I think to get the idea through. but not sure what yet.
   Andy: DONE - updated paragraph on index page and used that in intro section and on README.

Section. 1.1

1. Paragraph 1 - Move the tars defintion to the top of the documentation
   Andy: DONE

2. Paragraph 2 - Move th list of things it does (define servers, group the servers, define a default group or server to the top. This is what is important, not the YAML.
   Andy: The paragraph says what it does and what its format is, in one sentence. I could move the information about the format into a second sentence, but it seems more fluent if I don't. NOT CHANGED.

3. Paragraph-4 - What is the difference between description and access_via or is it just a way to break out the description in two parts?
   Andy: DONE - Added one-line descriptions and that contact_name and access-via are optional.

4. I wonder if there is a better word than "details" for the section where the user defines the target (definitions, settings, description (not so dood), etc.)
   DISCUSSION: Review fix.
   Andy: DONE - changed it to "user_defined".

5. Paragraph-5, security - "If you want to put the server definition file into a repository, you do not want" I would replace this with something more direct like "This Framework does not provide security for protected information like passwords but ..."
   Andy: DONE but differently. I don't like that suggestion, because it can be misread by the casual reader to say there is no security possible. Changed the text to a more neutral tone and described the two approaches more simply and understandably.

6. about paragraph 8 ("The server_definition parameter of the test function is a ServerDefinition object that encapsulates the server definition that is to be used for the test. ") try "The server_definiton parameter of the test function is a ServerDefinition object from the file for test of a single server. Pytest will invoke the test function for all servers that are to be tested.
   Andy: DONE - nearly as proposed

7. "You can also build your own pytest fixtures on top of this one that provide for for example an open session with the server
   a. This is first time this plugin is described as a fixture (on top of this one). Second. make general statement about building on top in first sentence and example in second sentence.
   Andy: DONE - a. the previous paragraph now states explicitly that it is a fixture, b. Split the sentences and improved them.

8. "Last but not least, the server definition file to be used and t" Drop the last but not least.
   Andy: DONE

Section 2.1 The general part of this just repeats what was in section. I wonder if the usage of 2.1 and the similar part of 1 should not be given just once.
DISCUSSION
Andy: Let me state my intention: I wanted the intro to be the same as the README, and thus it needs to be a reasonably complete but not so detailed description that can be read on its own and leave only details unanswered but not miss any of the major points. The usage then somehow needs to start providing more details. I started the usage from the perspective of a user writing test functions, that is why it starts with that and moves things like writing the server definition file down. Yes, there is some repetition as a result.

Section 2.2 "Server groups may be put into server groups at arbitrary nesting depth, as long as there is no infinite recursion anywhere." Something better than "infinite recursion anywhere" How about just recursion.,
Andy: DONE - changed to: "as long as there is no cycle (i.e. the resulting graph of server groups must be a tree)."

Section 2.4
"When the server definition file is placed in a repository, any server secrets such as passwords, private keys, etc. should not be in that file in clear text form." Replace with "Server secrets such as passwords, private keys, placed into this file may be publicly available and generally should be protected".
Andy: DONE - changed to: "If the server definition file is stored in a repository, it should not contain any passwords or other secrets in clear text."

That is as far as I got today.

General: Is there a way to say do all of them without a specific group "All" or something similar???
Andy: No. If you think that is needed, open an issue.

These environments are currently excluded from the complete weekly test, due to errors.
See for example this run: https://github.com/andy-maier/pytest-easy-server/actions/runs/713582322

The goal is to address the issues so that some or all of these environments can be enabled again.

Right now, the server definition capability in this package is inherently part of the pytest plugin. however, it would also be useful for daily work, completely outside of a test setup.

Should the server definition capability be moved to a separate package?

DISCUSSION

• Check that default exists
• Check that server group members exist

Issue is that currently, the file must be present at import time. This causes for example RTD not to build because the build runs with a current directory in the docs directory, and it is generally inconvenient as well.

The easy-server server and vault files support user-defined extensions. The easy-server project (as of version 0.8.0) provides support for validating the schema of these extensions, but the pytest-easy-server project so far does not support that.