Skip to content

17. The studio tested ​

Chapter 5 tested one button. The studio now tests itself: tut17_tested --test DIR draws the studio headless, on a virtual display with its title bar, and drives it as its user would, with keys, clicks, a drop, the file browser, a question, a run of the solver and the close button, checking its state after each gesture. It needs no display and no GPU, so it can run in CI as it is; the documentation's build runs it:

text
$ ./tut17_tested --test tut17-cases
[ok]     the title bar holds the studio's menus
[ok]     the title drags the window
[ok]     ctrl+o shows the file browser on the example cases
[ok]     Choose opens the case, the window's title says which
[ok]     typing edits the title, and the window's title marks it unsaved
[ok]     a drop asks before discarding the edit
[ok]     Discard opens the dropped case
[ok]     F5 runs the solver to convergence
[ok]     the task reads the field the solver wrote
[ok]     an input with the body out of the plate is refused
[ok]     and accepted once corrected
[ok]     the title bar's close button ends the studio
12 of 12 checks passed
docs/examples/src/tut17_tested.F90, run as tut17_tested --examples /tmp/figure-studio

The whole program: tut17_tested.F90. The test is the studio's own code, draw_studio, called by a loop of its own instead of the window's; nothing of the studio changes for it, except two lines that remember where the title field and the Discard button are.

What this chapter adds to chapter 16's program, tut16_robust.F90:

  • centre_of_last: The centre of the widget drawn last [pixels]
  • self_test: The studio driven headless as a user would; one line per check, an error stop if one fails
  • check: One check
  • frames: Draw n frames of the studio, as the main loop does; ended once next_frame says the studio ends
  • changed: draw_case, draw_dialogs

A studio without a display ​

fortran
call app%init_headless(1100_int32, 680_int32, decorations='figure') ! no window, no GPU: the title bar still drawn
call app%set_title('FIGURE studio')               ! headless mode has no title until one is set
call app%set_confirm_quit(.true.)
call view%init()
call frames(3_int32)
  • init_headless(width, height, decorations='figure') creates the contexts on a virtual display, without a window or a GPU, and draws the title bar FIGURE draws in a window: the frame is tested too (Headless testing).
  • init_headless takes no title: app%title() is '' until app%set_title gives one (The window's title).
  • Every call of frames(n) draws n frames, as the main loop does; input queued by figure_testing reaches the studio in those frames. Headless, every frame advances Dear ImGui's clock by 1/60 s, whatever the wall time.

The frame and the menus ​

fortran
call test_frame_rect('menus', r(1), r(2), r(3), r(4), found)
call check(found, 'the title bar holds the studio''s menus')
call test_frame_rect('title', r(1), r(2), r(3), r(4), found)
hit = test_frame_hit(0.5_real64 * (r(1) + r(3)), 0.5_real64 * (r(2) + r(4))) ! what the system is told
call check(found .and. hit == 'drag', 'the title drags the window')

test_frame_rect(part, ...) gives a part of the title bar as drawn in the last frame, and test_frame_hit(x, y) what the system is told there (chapter 8): the title drags the window. check(passed, what) is the test's own helper, not FIGURE's: it prints what after [ok] or [FAILED] and counts the failures, and the test ends with error stop if one failed.

Keys and the file browser ​

fortran
call test_key('shortcut', down=.true.)            ! ctrl, cmd on macOS
call test_key('o')
call test_key('shortcut', down=.false.)
call frames(6_int32)
call test_file_browser(shown, folder=folder, entries=entries)
call check(shown .and. any(entries == 'plate/'), 'ctrl+o shows the file browser on the example cases')
call test_file_browser_rect('entry:plate', r(1), r(2), r(3), r(4), found)
call test_click(0.5_real64 * (r(1) + r(3)), 0.5_real64 * (r(2) + r(4)))
call test_click(0.5_real64 * (r(1) + r(3)), 0.5_real64 * (r(2) + r(4)))   ! a double-click enters the folder
call frames(12_int32)
call test_file_browser_rect('ok', r(1), r(2), r(3), r(4), found)          ! Choose
call test_click(0.5_real64 * (r(1) + r(3)), 0.5_real64 * (r(2) + r(4)))
call frames(8_int32)
title = app%title()
call check(index(case_dir, 'plate', back=.true.) == len(case_dir) - 4 .and. &
           title == 'Heated plate - FIGURE studio', 'Choose opens the case, the window''s title says which')
  • test_key('shortcut', down=.true.) presses the platform's shortcut key, ctrl or cmd on macOS, so the same test passes on every system; test_key('o') then is ctrl+o (Synthetic input).
  • test_file_browser(shown, folder, entries) tells what FIGURE's file browser shows: the folder, the entries in the order shown (folders end in /); test_file_browser_rect('entry:plate', ...) and 'ok' give the parts to click. Two test_click in a row are a double-click.
  • app%title() is the window's title in every mode: a test reads it.
fortran
call test_click(title_at(1), title_at(2))         ! the title field, where the user clicks it
call frames(5_int32)
call test_key('shortcut', down=.true.)            ! select what is there
call test_key('a')
call test_key('shortcut', down=.false.)
call test_type('Plate B')                         ! and type over it
call test_key('enter')
call frames(8_int32)
title = app%title()
call check(trim(inp%title) == 'Plate B' .and. title == '* Plate B - FIGURE studio', &
           'typing edits the title, and the window''s title marks it unsaved')

The title field is where the studio drew it (title_at, from ig_item_rect in draw_case); test_type types into the focused field. A test checks what the user would see: the field's text, and the star in the window's title.

A drop and a question ​

fortran
drop(1) = dir//'/channel'
call test_drop(drop, 600.0_real64, 300.0_real64) ! a folder dropped on the window
call frames(6_int32)
call test_popup_rect(r(1), r(2), r(3), r(4), found)
call check(found .and. trim(inp%title) == 'Plate B', 'a drop asks before discarding the edit')
call test_click(discard_at(1), discard_at(2))
call frames(6_int32)
call check(trim(inp%title) == 'Cooled channel' .and. .not. edited, 'Discard opens the dropped case')

test_drop(paths, x, y) drops files or folders as a file manager would: app%dropped reports them in the next frame. The edit is unsaved, so the studio asks; test_popup_rect finds the question open, and a click on Discard answers it. The path is copied into a fixed-length array first (chapter 12's gfortran workaround).

The solver, the task, the checks ​

fortran
call test_key('f5')
call frames(3_int32)
do k = 1_int32, 1000000_int32                     ! frames until the solver ends (it runs in real time)
   if (.not. started) exit
   call frames(1_int32)
enddo
call check(index(run_status, 'converged in') == 1, 'F5 runs the solver to convergence')
do k = 1_int32, 1000000_int32                     ! and until the task has read its field
   if (size(field) > 0) exit
   call frames(1_int32)
enddo
call check(size(field) == inp%nx * inp%ny, 'the task reads the field the solver wrote')

The solver is a real process, and the task a real thread: they run in real time, while the test draws frames as fast as it can. The test draws frames until the run has ended and the field is read, with a bound, rather than a fixed number of frames that a slower machine would not meet.

fortran
inp%body_r = 0.5_real64                           ! the body out of the plate
call frames(2_int32)
call check(.not. can_run() .and. size(problems(inp)) == 1, 'an input with the body out of the plate is refused')
inp%body_r = 0.2_real64
call check(can_run(), 'and accepted once corrected')

The close button ​

fortran
edited = .false.                                  ! nothing to lose: close quits
call test_frame_rect('close', r(1), r(2), r(3), r(4), found)
call test_click(0.5_real64 * (r(1) + r(3)), 0.5_real64 * (r(2) + r(4)))
call frames(8_int32)
call check(ended, 'the title bar''s close button ends the studio')

A click on the title bar's close button, with nothing unsaved, ends the studio: next_frame returns .false., in headless mode as in a window. With an unsaved edit the studio would ask instead, as the drop above did.

The recordings of this tutorial ​

The recording above is a script too, docs/media/tut17_tested.rec: the program, its arguments and frames, then one input event per frame number, played by FIGURE's capture as a test plays its input. Every picture of this site is made so, and checked again on every push (The documentation's recordings shows this script and explains it).

What you learned

A whole application tested headless, by its users' gestures: keys and the platform's shortcut key, clicks aimed at where the program drew, typed text, a drop, FIGURE's file browser, a popup, the title bar; a real process and a real task waited for with a bound; and where its recordings come from. Reference: Headless testing, Screenshots and videos.

Run it: build it as chapter 7 shows (with tut12_heat beside it), then ./tut17_tested --examples /tmp/studio --case /tmp/studio/plate.

Next: 18. The studio on a cluster: the same studio in a web browser.

Released under the MIT licence.