Terminal Output Colouring

LNST supports coloured terminal output, which is enabled by default. This feature is highly configurable, and this page will explain the available configuration options.

1. Examples

Here are two examples of the output of LNST with the colouring with the extended colour palette:

2. Enabling/Disabling the Feature

The colouring is enabled by default. If you would prefer to turn it off, you can do it either temporarily by passing a CLI argument or permanently via a configuration option.

2.1 CLI Options

This option can be passed to both lnst-ctl and lnst-slave and it can be used to temporarily disable the colouring of the terminal output.

  -m, --no-colours                disable coloured terminal output

NOTE: The colouring is automatically disabled when the output is redirected to a file. In that case, you don't need to use this option.

2.2 Configuration Option

Alternatively, if you would rather keep the feature disabled completely, you can set the disable_colours option in the [colours] section of the respective configuration file (either lnst-ctl.conf or lnst-slave.conf.

[colours]
disable_colours = 1

3. Configuring Colours

The colours LNST uses for different parts of the output can be configured for both the controller and the slaves in their respective configuration files using colour presets.

3.1 Colour Presets

The colours of different parts of the output LNST displays are determined from colour presets. There are 10 presets currently available:

Preset	Description	Default Colour
faded	for debugging output	yellow
alert	for important messages	red
highlight	highlighted text	blue
pass	`PASS` colour	green
fail	`FAIL` colour	red
info	the `INFO` label	green
debug	the `DEBUG` label	blue
warning	the `WARNING` label	yellow
error	the `ERROR` label	red
log_header	the date and ip address in each log message	light-gray

The colours displayed by LNST can be altered by changing these colour presets in the configuration file in the [colours] section (works for both lnst-ctl and lnst-slave). Each preset is a tripple comprised of foreground colour, background colour, and bold flag.

Example Configuration

[colours]
# preset  foreground    background  bold flag
faded   = default       gray        0
info    = light-blue    default     1
warning = extended(208) default     1

The bold flag is a boolean value (true/false, 0/1, True/False). However, colours are a bit more complicated, as the colours can be configured either from the basic or the extended palette. The difference between using these two is explained bellow. If you would like to keep the default foreground/background colour, you can set it to default in both cases.

3.1.1 8/16 Colour Palette

Traditionally, terminals supported only very few colour options, typically 8 or 16. Today, it isn't quite so, as the vast majority of terminal emulators can work with up to 256 colours, nevertheless, these limitations for backwards compatibility are still there. Therefore, LNST uses these basic palette by default. With support of this limited colour palette, you can use the following colours in configuration:

black	dark-gray
red	light-red
green	light-green
yellow	light-yellow
blue	light-blue
magenta	light-magenta
cyan	light-cyan
light-gray	white

Example Configuration Using the 8/16 Palette

[colours]
# preset  foreground  background  bold flag
faded   = default     light-blue  0
info    = green       white       1
warning = white       light-red   1

3.1.2 Extended 256 Colour Pallete

Unfortunately, there are no aliases for the colours from the extended colour palette. Numbers from 0 to 255 are used to refer to different colours. The options are displayed on the picture bellow:

Example Configuration Using the Extended Palette

[colours]
# preset  foreground    background  bold flag
faded   = light-gray    default     0
info    = extended(228) default     1
warning = extended(208) default     1

NOTE: The palettes can be used together (some colours can be defined using the 8/16 and others with the extended palette).

4. Using Colours in Your Test Modules

Apart from the colouring that is there by default, you can actually add your own coloured logs when you are creating your own test modules. There are a few steps you need to take. First, you need to import the colouring functions, which are defined in the lnst.Common.Colours module:

from lnst.Common.Colours import decorate_string, decorate_with_preset

There are two functions available. The first one, decorate_string() allows you to paint the text with specific settings regardless of user configuration. The function takes three parameters:

def decorate_string(string, fg_colour=None, bg_colour=None, bold=False)

The first argument, string is the text to be coloured with fg_colour specified in the second argument. The colour of the background is determined from the third argument bg_colour. The last parameter is a bool flag that indicates whether the text should be printed in bold. The colour values here are specified in the same way as in the configuration file, e.g., green, extended(50), default. The downside of using this function is that the users won't be able to configure the colour you set here, it will always be the same. However, you can use the other function:

def decorate_with_preset(string, preset)

This allows you to colour the string with one of the predefined presets. The users then will be able to change the colour by changing the colour of the respective preset. All the presets that are available at the moment are enumerated in a table above in section 3.1.

4.1 Examples

logging.info("A part of this string will be " + decorate_string("red", "light-red") + "!")
logging.info(decorate_string("Fancy blue background", "default", "blue")

coloured_msg = decorate_with_preset("This is WRONG!!!", "alert")
logging.error(coloured_msg)