pchk.vim Plugin Checker Nov 09, 2020
Author: Charles E. Campbell <NcampObell@SdrPchip.AorgM-NOSPAM>
(remove NOSPAM from Campbell's email first)
Copyright: (c) 2016 by Charles E. Campbell pchk-copyright
The VIM LICENSE applies to pchk.vim and pchk.txt
(see copyright) except use "pchk" instead of "Vim"
NO WARRANTY, EXPRESS OR IMPLIED. USE AT-YOUR-OWN-RISK.
==============================================================================
1. Contents pchk pchk-contents {{{1
1. Contents.................: pchk-contents
2. PChk Manual..............: pchk-manual
3. PChk Usage...............: pchk-usage
3. PChk History.............: pchk-history
==============================================================================
2. PChk Manual pchkman pchkmanual pchk-manual {{{1
PChkTry PChkMake PChk PChkStep
Start a test by editing it, then run one of the following four commands:
:PChkTry : try the test. Will stop at :PChkSnapshot lines
and :PChkPause lines
:PChkRun : like PChkTry, but won't stop and won't check;
like PChkMake, but it won't create an
Expected/tst###.out file
:PChkMake : make an Expected/tst###.out file
:PChk : compare snapshot hashes currently obtained
with previously obtained expected test results
:PChkStep : step through each line of a test, not just at
the :PChkSnapshot commands.
Test File Commands PChkSnapshot PChkFeedkeys PChkPause
:PChkSnapshot : runs a hashing algorithm over the remote display.
Result is saved in/compared with Expected/tst###.out
:PChkFeedkeys ... : send keys to server. ^X translates to control
characters (ie. ^M is a ENTER)
:PChkPause : pause the test (uses input()). One may
* <cr> =continue
* c =check
* s =step
* t =try
:..cmd : send cmd to server to execute..
^\s*#... : echomsg comment in client vim (will not be sent
to server)
..cmd.. : send cmd to server to execute as a normal command
*..reply.. : netrw issues prompt; reply to it with this string
Special Variables: g:netrw_pchk
g:netrw_pchk : suppresses netrw version number from banner if true
(avoid spurious errors due to changes in netrw versions)
==============================================================================
3. PChk Usage pchkusage pchk-usage pchk-userguide {{{1
PChk provides a testing framework for plugins and requires:
* +clientserver (clientserver)
ie. :echo has("clientserver") needs to show a "1"
* gvim
ie. :echo has("gui") needs to show a "1"
PChk runs a gvim in a server (remote instance) which is started up
using a vim initialization file called pchk.vimrc; it is searched
for as:
The gvim being started uses
where "vimrc" is wherever pchk found pchk.vimrc from the list above.
A typical pchk.vimrc:
The last setting causes swap files to be placed in a directory
away from the current one (pchk was developed to support netrw
testing, and letting swap files litter the current directory
would alter test results).
PChk uses test files (input) which exercise the plugin. These test files
may
* have the remote gvim run commands (ex. :let g:netrw_liststyle=3)
* send keys to the remote gvim (as if a user had typed them) with
a translation of ^[A-Z] into associated control characters
* send normal mode commands
* send response strings
* take a "snapshot"
* query remote gvim for some status via an "assert"ion
PChk writes (output) and uses (input) Expected/*.out files which hold
the results of the test files.
The :PChkSnapshot command is of central importance to the PChk plugin.
It generates a hash (an integer) which is sensitive to:
* geometry: each tab, each window, what windows are next to which
windows (left, right, above, below)
* the contents of each window (text and syntax)
If any of these things that go into a hash changes, PChk will detect
that something differs.
A plugin may cause something to change (such as a setting or variable
value) that is not captured by a :PChkSnapshot. To capture such
changes, a
will act as if an ":echo command" was sent to the remote gvim and the
results therefrom are either entered into the Expected/*.out file or
compared with it.
As an example, consider tst007 for netrw:
This test does the following:
nothing, its just a comment
tells netrw not to include the version in the banner
changes the directory to dir001
tells netrw to generate a listing for the current directory
record/compare a snapshot of the remote gvim state
tells netrw to "edit" a subdirectory (dirA)
record/compare a snapshot of the remote gvim state
record/compare the result of comparing the b:netrw_curdir
variable with vim's current directory
issues a "c" normal mode command to netrw (see netrw-c)
record/compare the result of comparing the b:netrw_curdir
variable with vim's current directory
PChk can be run in one of four ways:
This command tells PChk to try the current file as a test. It
will stop at any :PChkSnapshot lines allowing one to see if
things are going as expected. It splits the test window and
shows the results of the hashing in the right side window.
This command runs PChk; like PChkTry, but it doesn't stop;
like PChkMake, but it doesn't record an Expected/tst###.out
file.
This command tells PChk to run the current file as a test
and to save the :PChkSnapshot and :PChkAssert results in
Expected/FILENAME.out for future comparisons.
This command tells PChk to run the current file as a test,
comparing the current :PChkSnapshot and :PChkAssert results
with the previously run Expected/*.out results.
This command will send a message for the remote server to
execute.
==============================================================================
4. PChk History pchk-history {{{1
v4: Nov 09, 2020 * made s:PChkRemoteSend(msg) into
pchk#PChkSend(msg). Included PChkSend as a
command in pchkPlugin.
v3: Aug 21, 2016 * PChkRun included
Nov 27, 2018 * Remote window contents, except for banner,
now cleared upon new invocation of PChk
Nov 27, 2018 * Tests are now always started from the
initial starting directory
v2: Apr 05, 2016 * included sensitivity to window names
(using expand("%:t") )
v1: Nov 25, 2015 * initial release
Feb 19, 2016 * included current window number in s:WinGeoHash()
==============================================================================
Modelines: {{{1
vim:tw=78:ts=8:ft=help:fdm=marker: