-
Notifications
You must be signed in to change notification settings - Fork 9
Custom Commands
Custom commands are used to provide additional or custom functionality within tst. It is an appropriate way to experiment with new commands before they are definitely added to the code base. Or to add customised functionality to some specific use or environment.
There are two types of commands in tst: internal and external. An internal command is a function invoked from within the running process of tst. An external command, on the other hand is a completely independent script that is invoked by tst in a separate process. Internal commands are usually faster to run, but are limited to be written as a python function. External commands can be slower and use more memory, but can be written in any programming language (limited only by the environment in which they will run). Both types of commands have access to tst services, so they can be easily integrated to the rest of the suite.
Distributable custom commands are assumed to be hosted in GitHub as gists. To install a custom command use the install tst command. Use this syntax:
tst install <username:command>
Where username is the name of the GitHub user that provides the custom command and command is the name of the command you want to install. The installation will present a disclaimer and notify the user about the risks of installing third party software. To update a custom command, simply run the same install command again.
Observation The install command will not allow the installation of a command with the name of a standard tst command.
Use
tst uninstall <command>
This command will remove all files installed for the custom command. You cannot uninstall standard tst commands.
To write an internal command create a python script containing a single function named tst_* and put the code inside a file named tst_*.py, where * stands for the name of the command you want to create. The function must receive a single parameter: args which is the list of arguments typed by the user in the command line. The only expected behaviour is that the function finishes its execution successfully. Obviously, it is assumed the function does not corrupt the config and tstjson objects as well as any user files, as the function has full access to them. Give the function a one line __doc__ string to make it the one line help used by the help command.
(Next release only) In the next release, the function will receive two additional arguments:
tstjsonandconfig. Thetstjsonis an object containing information about the current directory where the command was executed (orNoneif is not a tst directory). And theconfigargument is a json object containing information about the user's tst installation. In the current installation, raw dictionaries containing the same data can be obtained importingtstliband using the functionsread_configandread_tstjson.
To install and distribute the command save it as a GitHub Gist and use the installation mentioned above. To test and install it directly from the file see instructions below.
To write an external command create an executable file and name it tst-*. External commands can be written in any language. In fact, some of the standard tst external commands are written in bash and some are being developed in other languages as well. Make it have a --one-line-help option that prints a one line help string. It will be used by the help command of tst.
You can install a command directly from a local file. This makes it easier to install and test newly created custom commands, before deploying them to GitHub. To install a custom command from its file, use:
tst install <filename>
Observe that the install command infers that the installation is from a file because there is no : in its argument. However, observe that in this case, the argument is not the name of the command, but instead the filename itself. Despite this difference the file has to be named according to the conventions: tst_*.py for internal commands and tst-* for external ones.
Try installing the daltonserey:example, daltonserey:interno and daltonserey:extra commands (the extra command uses a two files gist). Take a look at their code in gist:
A different customization of tst is possible using plugins. With plugins you can customize the behavior of the test command, through hook functions that can be run before or after each test. This allows the user to provide a completely customized testing routine.