Re: [TCLCORE] Proposal for my contribution to Tk, request for comments

[Steve L. <st...@di...>]

Many thanks Erik, your efforts will be greatly appreciated.

I would encourage you to work in a branch off the trunk/main (i.e. in Tk9) and take care to remain cross-platform. If need be your work can be back-ported later.  Other than that, I’ll defer to Francois on the details of the test suite changes themselves.

Again, many thanks.

-- Steve
On 25 Nov 2024 at 4:54 PM +0800, elns <el...@xs...>, wrote:
> Hi all,
>
> I'd like to work on improvements to Tk on a more regular basis than before.
>
> I'm most interested in work on improving overview and maintainability of the Tk test suite. I
> believe that life can be made more easy for Tk maintainers. I also believe
> that more streamlining would ease the making contributions from Tk users
> (speaking for myself at least).
>
> Appended to this message, you find a list of proposed subjects. I'd very much appreciate comments on
> that. Please note that this list is meant to convey ideas and purposes. It is not meant to be
> anywhere exact about the workflow. That's for later.
>
> Subjects A and B are aimed at maintainability/overview. Subjects C and D are
> targeted at other improvements. If welcomed, I'd like to start with A and then B.
>
> Before starting off with anything, I'd like know:
> - whether the proposed subjects are welcomed.
> - whether my proposal interferes with someone else's idea's or work in progress
>
> Please feel free to raise anything else you think of as important, but which I didn't mention.
>
> (I already sent my proposal to Francois. I'll forward his response as
> the very first response in this thread.)
>
> Thanks in advance,
> Erik Leunissen
> --
>
> -- Proposed subjects --
>
>
> A. STRUCTURAl ASPECTS OF THE TK TEST SUITE
> ==========================================
>
> A.1 Collect utility procs
> -------------------------
> Utility procs are helper procs used by tests. I'm distinguishing global
> utility procs from local utility procs. Global utility procs are expected to
> be used by multiple test files. Local utility procs are expected to be used
> only in the test file that holds the proc definition.
>
> A.1.1 Collect global utility procs
> Currently, global utility procs exist in various test files and in the file
> constraints.tcl. I propose to move global utility procs and collect them in
> a new, separate file "utils.tcl".
>
> A.1.2 Collect test-file-local utility procs
> Collect them in a dedicated section somewhere at the top of the test file.
>
>
> A.2 Collect (more) test constraint definitions in constraints.tcl
> -----------------------------------------------------------------
> For example: pressbutton, failsOnXQuarz, failsOnUbuntu (the latter two
> for the time that they continue to exist ...)
>
>
> A.3 Make internal structure of test files uniform
> -------------------------------------------------
>
> A.3.1 Divide test scripts in explicit sections, each marked with a uniform
> section comment like:
>
> #
> # LOCAL TEST CONSTRAINTS
> #
>
> DISCUSSION: This idea targets an ideal situation, but I'm unsure whether
> it is feasible to maintain once the sections have been created.
> I'm unsure whether the degree of discipline, that it requires from (all)
> Tk maintainers, to put things where they belong can be "enforced".
>
> Sections envisaged for now:
> - file header comment containing general description of functionality and
> copyright statements, like the current state.
> - loading and configuration of package tcltest
> - definition of local test constraints
> - definition of local utility procs (see also A.1.2)
> - tests, possibly interspersed with setup and cleanup code for groups
> of related tests such as in canvas.test
>
> A.3.2 Prepend each individual test with a single blank line (two consecutive
> newlines) in all test files. This makes it more easy for the human eye
> to quickly see where a new test starts.
>
>
> A.4 Use common names for certain types of common utility procs
> --------------------------------------------------------------
> For example: there are various procs that combine the waiting or halting for a
> (fixed) amount of time with invoking "update" or "update idletasks". I
> envisage to collect them and give them the same prefix or suffix in the proc's
> name.
>
>
> B. TEST HYGIENE
> ===============
>
> B.1 Tests leave no new objects behind
> -------------------------------------
> Objects to check for:
> - interps
> - namespaces
> - global variables
> - procs
> - windows
> - queued events + idle tasks (this has priority in test files that
> are dedicated to events)
>
> B.1.1 Provide a common utility proc "checkTestsClean" that performs these checks
> while tests are executing. And possibly also provide a corresponding
> test option -checkclean that triggers this facility.
>
> B.1.2 Run these checks and list deficiences
>
> B.1.3 Fix deficiencies.
>
>
> B.2 Remove dependencies or interference between tests
> -----------------------------------------------------
> This subject may partially overlap with the previous subject B.1
>
> B.2.1 Provide a common utility command "runTestsSeparately" which runs each test
> in a new interpreter (yes, very slow!).
>
> B.2.2 Run the tests and list extra test failures when run separately.
>
> B.2.3 Fix deficiencies.
>
>
> B.3 Standardization of recurring test objects
> ---------------------------------------------
> Like A.3.1, this idea targets an ideal situation, but I feel it may be overdone.
> No priority for me as I see it now.
>
> B.3.1 Window position, size and background color
>
> B.3.2 Standardize the name of result variable: "result"
>
>
> C. REPLACE FIXED TIME DELAY COMMANDS/PROCS WITH FLEXIBLE PROCS
> ==============================================================
> Scattered throughout the test suite there are commands that halt or wait for a
> fixed amount of time. The drawback of using such fixed waiting times is that
> they need to accommodate a variety of user-systems for which the required
> waiting time varies. Therefore, these waiting times are rather long in order to
> err on the safe side. This slows down test execution.
> A related issue is that current usage of "after ms" or "_pause" etc. in many
> tests is undocumented. This makes it hard to understand for other persons
> besides the test author (if he remembers well) exactly what it is that's being
> waited for. This is a maintainability issue. (Using procs with names like
> "raiseDelay" are already an improvement in this respect IMO.)
>
> I propose to use a different approach of waiting where possible throughout the
> test suite. The core of this approach is the waiting for the servicing of a
> specific window event. See for example the generic proc "waitForWindowEvent"
> introduced with the tests for ticket #22349fc78a .)
>
> When developing the test script for the package windetect, I've been using this
> flexible waiting mechanism to my satisfaction. Obvious advantages are:
> - no more worries about the exact amount of time needed
> - improved maintainability (by using better proc names and comments)
> - a big speed-up of test execution (relative to the amount of time that's being
> waited for)
>
> To be fair: it is a challenge is to make such flexible waiting procs robust, and
> maybe there are cases where it appears not to work. I like that challenge.
>
> I envisage a common name structure for such waiting procs, and collecting
> them all in one place.
>
>
> D. LESS TEST CONSTRAINTS
> ========================
> As Francois already explained in his post to the TCLCORE mailing list
> (Wed, 23 Oct 2024 22:49:43 +0200).
>
> -- End of proposed subbjects --
>
>
> _______________________________________________
> Tcl-Core mailing list
> Tcl...@li...
> https://lists.sourceforge.net/lists/listinfo/tcl-core
>