Typically, Pumlhorse scripts are one part of a larger project. There is no required structure for such a project, but this lesson describes one possible setup. For demonstration purposes, we will build a test suite for an imaginary website for recipes.
This imaginary site has webpages that we want to test, as well as an HTTP API. We’ll organize everything under the
RecipeSite |___contexts | |___context.local.yaml | |___context.dev.yaml | |___context.prod.yaml |___tests | |___ui | | |___login | | | |___successfulLogin.puml | | | |___badPassword.puml | | | |___userDoesNotExist.puml | | |___search | | |___createRecipe | | |___puml_modules | |___api | |___recipe | | |___create_invalidData_returns400.puml | | |___delete_recipeExists_returns204.puml | |___puml_modules |___RecipeSite.local.pumlprofile |___RecipeSite.dev.pumlprofile |___RecipeSite.prod.pumlprofile
Directly under the RecipeSite folder, we have the
tests directories and a few
.pumlprofile files. Context files contain data that can change across environments or other use cases. Usually this consists of URLs, database connection strings, usernames, etc. The
tests directory contains the actual tests, separated into
api folders. The
.pumlprofile files are Profile definitions, which are similar to contexts in that they differentiate behavior between use cases. In this case, the profiles could be as simple as including the appropriate context file. However, it could be the case that we don’t want certain tests to run in production. Perhaps we want to reduce the number of scripts that run at one time to avoid overloading a certain server. These profile files can help facilitate that.
api folders, we have the actual
.puml files. There’s plenty of flexibility for defining folder structure and naming conventions, so just go with what makes sense for your team.
In the example above, you can see
puml_modules folders. These contain custom modules pertinent to the test suites. If you are writing your own custom module and you want it to live in the project (as opposed to a separate repository), it’s best to use the
puml_modules folder, rather than the typical
node_modules folder. This will help make sure it gets checked in to source control correctly, and provides better clarity. You can still use external modules via the
node_modules folders and npm alongside
puml_modules folders. Note: If you have the same module in both folders, Pumlhorse’s module resolution algorithm will give preference to
The advantage to using
node_modules folders is that you don’t have to worry about providing a path to the file. Pumlhorse will search for the file in those folders automatically using the Node resolution method. That is, in the script
myTests/RecipeSite/tests/ui/login/successfulLogin.puml, it will look in the following folders (in order):
In general, you should keep the modules at the lowest level possible (closest to the scripts that use it)
An alternative (or addition) to custom modules is using “partial” scripts. These scripts serve as reusable components that can be used across many scripts. See the run documentation for more details.