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:
$ ./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 passedThe 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 failscheck: One checkframes: Drawnframes of the studio, as the main loop does;endedonce next_frame says the studio ends- changed:
draw_case,draw_dialogs
A studio without a display
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_headlesstakes no title:app%title()is''untilapp%set_titlegives one (The window's title).- Every call of
frames(n)drawsnframes, as the main loop does; input queued byfigure_testingreaches 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
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
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. Twotest_clickin a row are a double-click.app%title()is the window's title in every mode: a test reads it.
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
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
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.
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
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.