Automate screenshots

[nojhan]

With the growing number of themes (a good thing!), we need a script to automate screenshots of prompts.

Description

The test script can generate three prompts examples, which can be used as normalized screenshots.

Those example should be displayed on some terminal and the screenshot taken, in both image and text form (for filling in the alternative text).
Possibly, this can probably be exported as HTML, too (for perfect, resolution-free display).

Incidentally, an automated generation of full prompts would also be good (also for debugging).
So far the test script can generate a "large" prompt, but not everything is enabled in it.
I remember this have been discussed, but I failed to find where.

How will this be useful?

This would allow fast updates of themes documentations.

[Rycieos]

A good idea.

The theme preview was designed to include everything in the "large" size. I can't remember exactly what I was thinking, but now that we have so many features, I think it makes sense to only include those enabled by default. Or, maybe we should include all features as mocks, but don't change the default config at all, and a user can load their own config so they can test a feature they really like but isn't enabled by default.

But it needs to be updated with each new data source with mocked data, which hasn't happened yet for the past few features.

Anyway, I agree on the automated screenshots. Not sure how easy that will be...

[nojhan]

Another thing is that we should have the ability to easily display prompts with fallback colors.

[Rycieos]

Another thing is that we should have the ability to easily display prompts with fallback colors.

Can you expand on that? Are you referring to the fallback colors I added in the Powerline themes?

[nojhan]

Everything that uses lp_terminal_format have fallback colors. I would want to automate tests/screenshots so as to display what a prompt would look like with the fallbacks triggered.

[Rycieos]

Ah ok. That should be fairly simple; we can either downgrade the TERM setting, or simply add a hook into the setup to force simple colors.

[nojhan]

While working on that, I realize that "presets" are a kind of light theme. However, they are in the "contrib" directory. A naive user may explore themes by looking in "themes" and thus not find presets. What about moving theme-related presets in "themes/presets"?

[nojhan]

So far, I managed to make automated screenshots using ImageMagick and a terminal emulator under X11.
Abstracting the terminal emulator seems like a complex task without adding argument management to the shell script (they all have small differences on their options).

tools/theme-screenshot.sh

#!/bin/bash
set -u

enough=4 # Sleep time in seconds.
emulator="terminator"
geometry="--geometry=1440x400"
title="--title"
command="--command"
more=""

# If a theme was given, use the theme and source all other arguments.
if [[ -z ${1-} || $1 == --help ]]; then
  printf '
Usage: %s theme [sourced files...]

Outputs a screenshot of example prompts based on a standard set of input conditions.
Should be run from the Liquid Prompt root directory.
Outputs a binary PNG file on standard output, thus should be redirected to a file.

Example usage: %s unfold themes/unfold/unfold.theme contrib/presets/colors/256-colors-dark.conf > unfold.png

If you see an error "no window with specified ID exists", try increasing the "enough" parameter.
May only work under an X11 graphical server, depending on your ImageMagick configuration.
' "$0" "$0"
  exit 2
fi

# Generate a random ID to ensure recognizing the window.
rid="LP_$(xxd -l 8 -ps /dev/urandom)"

# Default security policy of ImageMagick is to disable printing on standard output,
# so we are forced to pass by a temporary file.
tmp="$(mktemp --suffix=.png tmp_XXXXXXXXXX)"

# Open a window for some seconds and take a screenshot after some seconds.
$emulator $geometry $title $rid $more $command "$(pwd)/tools/theme-preview.sh $* ; sleep $enough" & (sleep $enough ; import -window $rid $tmp)

# Output the binary on stdout.
cat $tmp

[Rycieos]

So far, I managed to make automated screenshots using ImageMagick and a terminal emulator under X11.

Well I agree, implementing a terminal emulator is way out of scope (and overkill). I think your idea is fine, but the big issue is portability. I do most of my development work on Linux, but I do it through MacOS or Windows desktops (either SSH or WSL), for various reasons.

I did get Terminator running correctly in WSL, but I cannot get ImageMagick import to find the window. I am not sure that is something that we can fix. I could dig out an old laptop and put some sort of Linux on it, but that would be a painful part of each release for me. Right now it would be less work for me to manually screenshot than to get out my old laptop to run this script.

Even if we got that working, there are a few issues yet with your script so far:

• The font and font size are not set, and could be anything.
• This captures the whole script output. Previously we had three screenshots per theme, for the three outputs of theme-preview.sh. But there is no easy way to know the boundaries of those prompts, since a theme can add as many extra characters and lines as it wants.
• Similarly, your default size of the terminal might not even be big enough for more verbose themes.

I think your approach might still be doable. But if it was me, I would have a set of params like font, font size, and terminal width, and have someone manually screenshot each output. Then a script could take those screenshots and:

1. Crop to a standard size. (Somehow detect where the top left most pixel of text is, and add or subtract consistent padding around all text.
2. PNGcrush the final image.

[nojhan]

That's all valid points. I started adding an height parameters already in refactor/default-theme. What I did for presentation was to have a script with heights configured by hand for each theme I wanted screenshots for.

At the end I don't think we need to aim for a fully automated and generic system. There will always be some setup on which it will not work, and I am not sure it would be worth the effort. If it is just for having a screenshot for releases, we can very well do it by hand and just standardize a screenshot file name (like <theme_root>/docs/screenshot.png) so that we can point the doc to it for any theme.

But for me, it is helpful to have at least a script I can configure to get an up-to-date view on several themes at once, once in a while.

[Rycieos]

This isn't a release blocker, so it is going to miss v2.2.0.