http://invisible-island.net/
Copyright © 1996-2023,2024 by Thomas E. Dickey
Vttest tests the compatibility (demonstrates the non-compatibility) of so-called “VT100-compatible” terminals. In conformance of the good old hacker traditions, the only documentation of this program is the source code itself. To understand it, you also need a copy of the original VT100 manual from DEC.
Additional tests (past version 1.7) are provided for analysis of vt220 through vt520 terminals, as well as variants of xterm.
Vttest was written in 1983-1985 by Per Lindberg at the Stockholm University Computing Center. The last version was 1.7b (1985-04-19). Per Lindberg later distributed 1.7b via the Usenet mod.sources group (Volume 7, Issue 16, September 2, 1986). It became an established part of the Unix source archives, e.g,. as noted in these postings from 1988.
I began this version in May 1996 (starting with 1.7b) to support changes that I am making to xterm. The program has grown from about 2400 lines to more than 18,000 lines of code. See the changelog for details.
I changed the version number to 2.0 in the initial release, in 1996, and went up to 2.7 shortly after. Since then, the patch-date is the effective version number.
Most of my visible changes are via two menu entries at the bottom of the main screen:
However, I restructured the entire program, adding screens to existing tests, and menu entries (for instance in the terminal reports). In the restructured program, it is much simpler to add menu entries, since they are built from tables rather than case statements.
On the other hand, I kept the overall indentation style of the program. There are no tab characters.
VT100's never did color.
My original motivation for working on vttest was to provide a way to test the color changes I was making for xterm. Drawing colored text is straightforward. Drawing colored backgrounds presents many choices. For instance:
None of those choices are automatically "right" or "wrong". Designers of different terminals (and emulators) have chosen to implement color in different ways.
For xterm, I chose to match the Linux console behavior. That was a starting point. But (see below) I continued past this point, implementing features from VT220 and later, including controls (DECSCA) that can protect against erasure.
The particular erasure choices used in xterm and Linux console are modeled in ncurses as the back color erase (bce) feature. Early on, we (I and Alexander V. Lukyanov) found that the bce feature was nowhere defined precisely, and settled on the current behavior. Other terminals (such as rxvt) do not exactly match this set of choices, so controls which differ are not in the corresponding terminal description.
I added screens to vttest to illustrate the bce behavior, helping to ensure consistency.
For instance, this was once of the earlier screens I wrote to demonstrate and test erases against the bce color model:
Before Erase After Erase
The terminal also has to fill color properly for double-sized characters. Here are examples with and without font support for double-sized characters:
Using scaled fonts Without scaled fonts
Even Linux console has had occasional issues, where it is inconsistent, e.g., a blunder in 2008 as reported on the Linux kernel mailing list here by Alexander V. Lukyanov. The problem was introduced here, and broke the bce feature of Linux console for several months. Vttest might have been useful in that case.
Double-sized characters required some work on xterm. Initially, it only drew normal sized characters with spaces in between (and there were a few issues to resolve). Xterm now draws double-sized characters using scaled fonts (a feature introduced by XFree86). Here is an example from the VT100 tests:
After I had been working on vttest for a while, I realized that xterm had features (other than the obvious case of function keys) that were not found in a VT100. These control sequences switch to a different character set for just one character (a single shift) or until undone (locking shifts). The VT100 line-drawing characters are a special case of the latter.
The set of single- and locking-shifts are features of the more advanced VT220 terminal. Seeing that, and understanding that it would allow xterm to be more useful to people around the world, I decided to fill in the missing pieces to make a workable VT220 emulator. Years later, of course, UTF-8 became a more valued feature. But I use different programs than vttest for testing xterm's UTF-8 support.
Some of the features (in particular the character sets) are visible only when the terminal identifies itself as a VT220 or above. For instance, the top-level menu "Test of character sets" shows only the VT100 character sets for VT100s:
But for VT220s (e.g., xterm with the command line
option "-ti 220"), vttest shows a
menu, with the VT100 character sets as an option:
VT220s provide something like ISO-2022 support for several European encodings. Here is an example using the locking shifts, showing French and Italian:
Incidentally, the VT220 and up can be switched into a mode where they identify themselves as lower-level models (analogous to the VT100/VT52 switching). You can do this in vttest using menu 12:
The Linux console used to recognize 8-bit controls. I gave advice to Albert Cahalan (see links), who used vttest to identify and repair most issues. However, later work to change the console driver to support UTF-8 broke that, though comments in the code still claimed that the feature was supported. Early in 2006, I submitted changes which were applied to the console_codes manpage, including the BUGS section. This paragraph is pertinent:
Some older kernel versions (after 2.0) interpret 8-bit control
sequences. These "C1 controls" use codes between 128 and 159 to
replace ESC [, ESC ] and similar two-byte control sequence initiators.
There are fragments of that in modern kernels (either overlooked or
broken by changes to support UTF-8), but the implementation is incom-
plete and should be regarded as unreliable.
DEC's terminals were all upward-compatible:
Each model also provides more new features than the total in its predecessor. Not all features are useful for a terminal emulation (such as the dual-session feature of VT420). I have implemented tests for the features which either are in xterm, or are simple extensions (such as the variations on status responses).
Vttest organizes these according to the terminal type. Features found in ISO 6429 but not in a particular DEC terminal are via separate menu choices from XTERM and the VTxxx flavors:
Early on, I found that ECH (erase character) is a VT220 feature rather than VT102. It is perhaps the most commonly implemented extension of “VT100 emulators”.
As it is implemented in rxvt (unlike xterm and Linux console) it does not behave the same with regard to color as ED (erase display). After some discussion, it was determined that
For example, I recall using more than one terminal emulator with “VT340” and color, for instance TNVTPlus (developed by FTP Software, Inc.). That, by the way, differed from xterm regarding the way color was set when scrolling in "blank lines". There are as noted several choices, and none are blessed by an official standard. Vttest demonstrates the set of choices used in xterm and Linux console.
Xterm implements several features from models past VT220. One of the more interesting is the ability to work with rectangles on the screen (from VT420). That is (both in vttest and xterm) only provided when the terminal identifies itself as (at least) a VT420:
As a VT100 As a VT420
Given the proper configuration, vttest shows rectangles. As an extension, xterm supports color:
Monochrome Color (XTerm)
ISO 6429 has several features (including scrolling not implemented by DEC terminals). The most useful set of tests is the color menu:
The window modify- and report-operations attributed to dtterm (because that was the only extant usage in 1996) had appeared in the X10 "6.6b" version xterm. Like its successors through X11R6, there is no changelog, so it was not possible to determine when/where the features originated. But they predate dtterm. Some additional information is given in XTerm Control Sequences.
The original distribution of vttest used licensing terms which were problematic ("noncommercial"), e.g., for the Debian packagers:
This software is (c) 1984 by QZ
Non-commercial use and copying allowed.
If you are developing a commercial product, and use this program to do
it, and that product is successful, please send a sum of money of your
choice to the address below.
I contacted Per Lindberg in 2007, and suggested that it be changed to a BSD license. He agreed. My changes have always been compatible with that.
Here are additional screenshots.
There are numerous references on the net to vttest. Here are a few of the more interesting ones:
Usually vttest is a separate package. However OpenSuSE bundles vttest within the xterm package.
FreeBSD (likewise NetBSD, OpenBSD) had a source (and typically installed vttest) as part of PCVT. The PCVT console driver is not much used now, but (like xterm of the same era) aimed at good VT220 emulation. Here is a place to read about it.
Since 2005 (see also manned.org), vttest has been provided as a port (not part of the base system).
Recently (at least since 2009), FreeBSD has been revising the SYSCONS console driver (the "TEKEN_XTERM" feature seen here). As noted here, vttest has been useful in this development.
rxvt used to have a bundled copy of 1.7b (see changes.txt).
Mark Olesen dropped it from rxvt in his final release 2.18
(announced August 2, 1996) to reflect my work on
vttest. However, its presence in rxvt's source
(combined with my having sent Mark a patch in April 1996 to
improve rxvt's handling of SGR 39/49 default colors) was what
led me to start adding the color-related tests to
vttest.
KDE konsole used to have a copy of 1.7b, which I noticed in 1.0.2 (2001) when responding to a bug report where konsole had incorrectly implemented xterm's SGR 1049 (no cursor save/restore was done). Ultimately it turned out that the bug had been fixed, but was poorly communicated since the corresponding upstream bug report was not cited in Debian's update ("fix konsole" can cover a lot of territory), nor was there any changelog note in KDE describing the change.
Vttest comprised most of the files in the "tests" subdirectory. It was removed in 2009, according to the commit comment due to "license issues/age" (and is not mentioned in its changelog).
Konsole's copy had been modified, of course, to work with POSIX termio, although it was done inline (rather than moving the repeated ioctl's to a separate function). Seeing that vttest was apparently being used made it puzzling that at the time Konsole used a nonstandard response for its terminal identifier (the primary device attributes):
if (getMode(MODE_Ansi))
// sendString("\033[?1;2c"); // I'm a VT100 with AP0 //FIXME: send only in response to ^[[0c
sendString("\033[>0;115;0c"); // I'm a VT220 //FIXME: send only in response to ^[[>c
else
sendString("\033/Z"); // I'm a VT52
That is, it was returning xterm's secondary response. The “115” was xterm's patch level in late 1999. However, that was partially corrected around the same time as the bug report— mentioned above. The string is (as of December 2011) returned as the response to the secondary device attributes control.
The comment “I'm a VT52” should be “VT100 emulating VT52” (real VT52s respond differently).
old source on Aminet, from 1987
older source, from 1983
broken console fails vttest (Albert D Cahalan, 20 Jan 1999)
Terminal.app is
not your grandfather's VT100 terminal (Tao of Mac).
This is an example of how vttest is used to validate
the correctness of a terminal.
By the way, the comment "passes more suites" refers to an earlier source (apparently not available) whose writer was confused about xterm's support for double-sized characters, stating that Terminal.app did this while xterm did not. Xterm's done this since 1998. Since Terminal.app is an OS X application, it cannot be older than 2002.
The existing article (from 2005) goes on to comment that Terminal.app does not handle mouse location reporting. That gives a clue: As of 2014, Terminal.app as a rule does not handle the VT220 and higher-level control sequences which comprise the bulk of the screens in vttest. It is not xterm. Perhaps its developers intended it to compete with dtterm, which it more closely resembled at that point in time.
The System Under Test page only skims the surface of testing a terminal.
tack is an interactive tool like vttest, used for testing terminal descriptions. A terminal description provides details about the most commonly used features (which applications and libraries such as ncurses may use portably).
When I test a terminal description, I rely on vttest and tack and make notes on the problems found (see terminfo.src for examples)
The ncurses-examples (whether separate or bundled with ncurses) indirectly test terminal features, due to their reliance upon the line-drawing and character encoding support of the terminal.
XTerm's sources include several scripts which demonstrate features that generally are outside the scope of vttest e.g., because they are specific to xterm rather than DEC terminals (see snapshot).
I have more than two thousand scripts, aside from those which are bundled with one of the programs I develop. Some of these scripts provide more in-depth testing of terminal capabilities. If a given script provides the only test for a feature, I generally move it into the collection bundled with xterm.
These are tools which others have developed:
wraptest
– DEC VT terminal line-wrapping semantics
(Mattias Engdegård).
Beyond its immediate usefulness, Engdegård pointed out a useful document which provides details on similar obscure features of DEC's terminals:
DEC STD 070 Video Systems Reference Manual (EL-SM070-00, December 1991).
esctest
– Automatic unit tests for terminal emulation
(George Nachman, original
site).
While vttest uses query/response control sequences to determine if the responses are valid, it relies upon (a knowledgeable) user to inspect test screens. Rather than inspect each test screen, this set of scripts uses the VT420 DECRCRA control sequence to infer the contents of the screen at different points. It cannot test interactive features, and there are large areas (such as NRCS, C1, UTF-8) which are not yet covered (writing in August 2019), but within its intended scope is useful for regression testing.
When I test with esctest, I use a script which exercises it for five levels (VT100 to VT525), in non-UTF-8 and UTF-8 (wide) configurations. The test results differ slightly between the two configurations. Neither comes close to testing all of xterm:
vttest covers far more of xterm than that (about twice as much). I have special scripts which cover some of the remainder. To make it easier to measure this, I modified vttest to enable it to re-read its log file as a command script. By doing that, I could use lcov to determine if I was using most of the available tests. For some tests, there are many combinations of parameters via the menus, and it takes time to develop those scripts. Here are results from October 2024:
With those scripts, as well as about 30 scripts and tack and the ncurses test-program, I produced this report:
Those scripts include esctest, but it contributed only 2% of the coverage because almost all of it duplicates vttest or the other scripts.
