Add a page documenting the Unit Testing plugin

[jitseniesen]

Pull Request

Pull Request Checklist

• Read and followed this repo's Contributing Guidelines
• Based your PR on the latest version of the correct branch (master or 4.x)
• Checked your writing carefully for correct English spelling, grammar, etc
• Described your changes and the motivation for them below
• Noted what issue(s) this pull request resolves, creating one if needed

Description of Changes

Add a page documenting the Unit Testing plugin.

I did not make any effort optimizing the pictures and videos for size. If there are instructions on how to do that, please let me know.

Issue(s) Resolved

Fixes #329

[CAM-Gerlach]

Thanks for all this, @jitseniesen ! I'll try to take a more detailed look at it tomorrow.

I did not make any effort optimizing the pictures and videos for size. If there are instructions on how to do that, please let me know.

Unfortunately, not really at the moment, since the most impactful steps that make the biggest reduction require a degree of expert hand-tuning, and the most efficient way for that is to just have me do it and commit back to the PR branch. Would you like me to take care of that for you?

For the PNGs, it's just reducing the color depth to a ≈64-ish color palette (depending on the context, but that typically works fine with some margin), occasionally downscaling the resolution with the right algorithm (in specific circumstances) and then running optipng, which can reduce file size by an order of magnitude or more.

For the GIFs, it's a lot more complicated, and involves (with ffmpeg) a combination of downsampling the resolution (with the appropriate algorithm), downsampling the frame rate, speeding up the clip, trimming the start and end, adding a pause if necessary at the end, ropping, reducing the color depth, palettizing with an efficient strategy, then optimizing with gifsicle with -O3 and --lossy enabled. In total, this can reduce the file size by anywhere from 1-3 orders of magnitude, depending on how well optimized the original is (in a recent case, we reduced 50 MB (!!!) GIFs to on the order of 50 KB), with minimal visible quality loss. Ideally, it's done directly from the original video files for maximum quality and efficiency (which sometimes is actually higher than the original GIFs), though so long as the original GIF conversion was pretty good, it can usually be done from the existing GIFs without much loss.

FWIW, the full invocation is

TEMP_FILENAME="temp_processed"; ffmpeg ${START:+-ss 00:00:}${START:-} ${END:+-t 00:00:}${END:-} -i ${FILENAME}.mp4 -vf "${CROP:+crop=}${CROP:-}${CROP:+,}setpts=${SPEED:-1}*PTS,fps=5,${SCALE:+scale=}${SCALE:-}${SCALE:+:flags=lanczos,}${PAUSE:+tpad=stop_mode=clone:stop_duration=}${PAUSE:-}${PAUSE:+,}split[s0][s1];[s0]palettegen=stats_mode=diff[p];[s1][p]paletteuse=diff_mode=rectangle:dither=none" -loop 0 -y ${TEMP_FILENAME}.gif && gifsicle --no-conserve-memory -O3 --lossy ${TEMP_FILENAME}.gif > ${FILENAME}.gif && rm ${TEMP_FILENAME}.gif

With FILENAME being required, and CROP, SCALE, START, END, SPEED and PAUSE being set if relevant. Example variables set for one GIF:

FILENAME="editor-class-function-selector"; CROP="736:ih-2:0:2"; SCALE=; START=01; END=; SPEED=0.5; PAUSE=2;

It would likely be easiest to just take care of that for you and I commit the result here (to be squashed or fixup'd in). If you want to share the original screen captures (e.g. via Google Drive) you can, though I can always give it a shot from the GIFs first, which usually produce nearly the same resulting quality and not too much larger file size. Thanks!

[jitseniesen]

Unfortunately, not really at the moment, since the most impactful steps that make the biggest reduction require a degree of expert hand-tuning, and the most efficient way for that is to just have me do it and commit back to the PR branch. Would you like me to take care of that for you?

Yes, please do.

If you want to share the original screen captures

I used peek to make the videos, which automatically converts them to GIF. When writing this, I saw that "peek" is now deprecated, so probably not the best choice. Have a look at the GIFs and if they are bad or need to be re-recorded for another reason, let me know. Any suggestions for recording tools on Linux?

[CAM-Gerlach]

Have a look at the GIFs and if they are bad or need to be re-recorded for another reason, let me know.

I looked over each of the existing GIFs, and they all looked good enough to use and convert as-is, so no need to remake them. I hope to take care of that, as well as reviewing the PR, tomorrow. As for fixing any minor formatting or reST syntax issues, would you prefer I made those as review suggestions, as commits (easiest) or as a separate followup PR? I'd save any non-trivial suggestions that touch the actual content for comments, of course.

Any suggestions for recording tools on Linux?

Not really sure, sorry; I mostly use Linux on the CLI rather than with a GUI. The Peek deprecation noticed mentioned Kooha, which looks pretty cool. I know a fair number of people use Licecap, but not sure if that works on Linux.

[jitseniesen]

As for fixing any minor formatting or reST syntax issues, would you prefer I made those as review suggestions, as commits (easiest) or as a separate followup PR?

If it is easiest for you just to commit them, then go for it.

[juanis2112]

Hey @jitseniesen, in case it is of any help, I tested a bunch of Gif generator tools and didn't like must of them because they had low flexibility for editing so I used to record videos on OBS and then used ffmpeg to convert them to gifs.

[CAM-Gerlach]

Yup, and that's also what I do too and generally recommend. In fact, the above ffmpeg invocation I mentioned is a direct evolution of what @juanis2112 and I developed for the original set of GIFs currently in these docs, with a bunch of changes and enhancements since then from testing and experience to make the resolution/quality higher and the file size smaller, as well as making it somewhat easier to use by putting all the key parameters into variables.

No need to remake your GIFs now (Juanita and I both know how much work that is), I can work with the GIFs as source—but if you contribute more GIFs in the future, I'm happy to take care of the conversion and tuning myself if you share your captured videos on Google Drive, and am also happy to walk you through how to pick the right parameters for a specific GIF to get good quality and small filesize (though some of that just comes with experience).

[jitseniesen]

Thanks @juanis2112, that is helpful. OBS was one of the tools that I was seriously considering, because I have used it before to give online lectures. I was afraid that OBS is overkill but I'll give it a try next time.

[CAM-Gerlach]

Sorry for the long delay and thanks for your patience! I've been busy finishing up my research to prepare for my defense soon, as well as taking care of other things. I've pushed the converted/optimized PNGs and screenshots to the PR (as well as developed a reusable invocation of the PNG optimization for the future), and hope to be able to review the rest of the textual content by the end of this week.

I've optimized the PNG screenshots with ImageMagick (strip alpha channel & reduce to 8-bit with 64 parallelized colors) and Optipng (compression optimization), plus pre-cropping the transparent/drop shadow area for one image, which resulted in a total 2.6x size reduction (375 KB to 147 KB) maintaining perceptually lossless quality. Here's the now-refined and standardized invocation that takes care of all of them in one go:

find . -type f -name "*.png" -exec bash -c 'convert {} -background white -flatten -colors 63 +dither {} && optipng {}' \;

As for the GIFs, I followed the procedure described above, resulting in a similar 2.6x overall total size reduction (1025 KB to 399 KB) with only a modest quality tradeoff (a bit lower visible resolution and color accuracy), with the following arguments for each:

FILENAME="unittest-expand-collapse"; CROP=; SCALE=; START=; END=; SPEED=0.75; PAUSE=;
FILENAME="unittest-slow-run"; CROP=; SCALE=; START=; END=; SPEED=1; PAUSE=1;
FILENAME="unittest-sort"; CROP=; SCALE=; START=; END=; SPEED=0.75; PAUSE=;
FILENAME="unittest-goto"; CROP="iw:ih-1:0:1"; SCALE="611:335"; START=; END=; SPEED=0.75; PAUSE=1;
FILENAME="unittest-run"; CROP="iw:ih-1:0:1"; SCALE="611:335"; START=; END=; SPEED=0.75; PAUSE=;
FILENAME="unittest-show-output"; CROP="iw:ih-1:0:1"; SCALE="611:335"; START=; END=; SPEED=0.75; PAUSE=2;

[jitseniesen]

Sorry for the long delay and thanks for your patience

No worries, it took me months to finally get to writing it, so a few weeks more is not a big deal.

[jitseniesen]

@CAM-Gerlach bump