8294156: Allow PassFailJFrame.Builder to create test UI #15665

aivanov-jdk · 2023-09-11T15:36:56Z

This enhances the Builder pattern added in JDK-8294535 with a new method testUI which allows passing a lambda expression or a method reference to create the test UI window.

The PassFailJFrame will automatically call the method on the EDT to create the UI, add it to the internal list of windows, install the window closing listener and finally position and show both the instructions and test UI.

Alternatively, you can pass an already created window.

The main method of a manual test could look as simple as a sequence of calls:

    public static void main(String[] args) throws Exception {
        PassFailJFrame.builder()
                      .instructions(INSTRUCTIONS)
                      .testUI(() -> createTestUI())
                      .build()
                      .awaitAndCheck();
    }

where createTestUI returns a test UI window.

Progress

Change must be properly reviewed (1 review required, with at least 1 Reviewer)
Change must not contain extraneous whitespace
Commit message must refer to an issue

Issue

JDK-8294156: Allow PassFailJFrame.Builder to create test UI (Enhancement - P4)

Reviewers

Alexander Zvegintsev (@azvegint - Reviewer) ⚠️ Review applies to 70256b66
Phil Race (@prrace - Reviewer) ⚠️ Review applies to 0be29d16

Reviewing

Using git

Checkout this PR locally:
$ git fetch https://git.openjdk.org/jdk.git pull/15665/head:pull/15665
$ git checkout pull/15665

Update a local copy of the PR:
$ git checkout pull/15665
$ git pull https://git.openjdk.org/jdk.git pull/15665/head

Using Skara CLI tools

Checkout this PR locally:
$ git pr checkout 15665

View PR using the GUI difftool:
$ git pr show -t 15665

Using diff file

Download this PR as a diff file:
https://git.openjdk.org/jdk/pull/15665.diff

Webrev

Link to Webrev Comment

Instructions for FileChooserSymLinkTest are rendered in HTML.

Each text component (JTextArea or JEditorPane) are configured in its own dedicated method. This avoids unnecessary type casts.

It reverts the accidental change where I unwrapped call to createUI

Moved it to a named class, saved the instance in a field. It's to be used with test windows.

The Builder now provides a method to create test UI, PassFailJFrame automatically invokes the method reference on the EDT and then shows both the instruction frame and the test window.

Also clean up the doc for disposeWindows().

The WindowClosingHandler is used both for the instruction frame and for test UI windows. Also add blank lines to separate different parts of the class.

It's not supposed to be extended.

bridgekeeper · 2023-09-11T15:38:29Z

👋 Welcome back aivanov! A progress list of the required criteria for merging this PR into pr/15660 will be added to the body of your pull request. There are additional pull request commands available for use with this pull request.

openjdk · 2023-09-11T15:40:26Z

@aivanov-jdk The following label will be automatically applied to this pull request:

client

When this pull request is ready to be reviewed, an "RFR" email will be sent to the corresponding mailing list. If you would like to change these labels, use the /label pull request command.

mlbridge · 2023-09-11T15:45:07Z

Webrevs

azvegint · 2023-09-12T13:04:09Z

test/jdk/java/awt/regtesthelpers/PassFailJFrame.java

+
+    @FunctionalInterface
+    public interface WindowCreator {
+        Window createTestUI();


Sometimes we may need to create more than one window(e.g. some DnD test with two windows).
Perhaps we should consider that here by adding List<Window> createTestUI().

Sometimes we may need to create more than one window(e.g. some DnD test with two windows). Perhaps we should consider that here by adding List<Window> createTestUI().

I thought about it. Yet I couldn't find a simple scenario where multiple windows need to be created. When there are multiple windows, you have to position them. The positions of the windows may depend on the position of the instruction frame. In #12447, Harshitha @honkar-jdk managed many test windows.

I decided to handle the most common scenario: one test window.

This can be extended in the future by creating WindowListCreator interface, its createTestUI method will return a list or a collection: List<Window> or Collection<Window>. Changing the signature of the existing WindowCreator.createTestUI could also be possible without breaking backwards compatibility.

Now that I think about it more, you have a point… Why not allow passing a list of windows right away? However, to test this case I'll need a (simple) scenario where multiple windows are created.

However, to test this case I'll need a (simple) scenario where multiple windows are created.

For example test/jdk/java/awt/event/MouseEvent/SpuriousExitEnter/SpuriousExitEnter_2.java is not converted to use PassFailJFrame, but shows instruction window and two test windows.

For these test windows, we can safely reduce the width a lot and arrange them in a row.

Probably we could add some other sophisticated layouts later, e.g.:

But this kind of layout seems to be beyond the scope of this PR, I just wish we hadn't missed the option to add multiple windows at once.

But laying out the test windows is really a problem. With one window, the framework already provides a way to position the window, it is applied to the primary test window.

Before showing other windows, they need to be positioned.

There could be a callback so that the test developer is able to position the windows. In the future, we may add simple layouts to perform this task automatically.

But this kind of layout seems to be beyond the scope of this PR, I just wish we hadn't missed the option to add multiple windows at once.

I agree, it's better to implement it right away. I didn't think about it as viable solution because of positioning issues.

It is possible to lay out test windows like this:

azvegint · 2023-09-12T13:06:02Z

test/jdk/java/awt/regtesthelpers/PassFailJFrame.java

-     * Dispose all the window(s) i,e both the test instruction frame and
-     * the window(s) that is added via addTestWindow(Window testWindow)
+     * Disposes of all the windows. It disposes of the test instruction frame
+     * and all other windows added via {@link #addTestWindow(Window)}.


Shouldn't we mention here a window added by testUI via builder?

Shouldn't we mention here a window added by testUI via builder?

I don't think it's necessary: the builder uses addTestWindow under the hood. It's the builder that requires documentation.

In fact, the entire class requires a bit of TLC for documentation. I even wrote some after Lawrence @lawrence-andrew created the first version of PassFailJFrame but I never finished it. Even this part was implemented nearly a year ago.

I plan to create a wiki page on the client-libs wiki to describe creating manual tests with PassFailJFrame.

Shouldn't we mention here a window added by testUI via builder?

I don't think it's necessary: the builder uses addTestWindow under the hood. It's the builder that requires documentation.

In fact, the entire class requires a bit of TLC for documentation. I even wrote some after Lawrence @lawrence-andrew created the first version of PassFailJFrame but I never finished it. Even this part was implemented nearly a year ago.

I plan to create a wiki page on the client-libs wiki to describe creating manual tests with PassFailJFrame.

Just saw this, and it mirrors what I wrote in another PR that we need docs, but I believe they are best placed inside the source itself. Not everyone who can update this source can update the wiki.
That doesn't preclude you from putting more examples on the wiki and a reference to it from the source but I still think there should be docs in the source.

Include how to use this feature and something like to the builder example you have here might be good too.

In fact, I started writing javadoc for PassFailJFrame while Lawrence and I discussed it. I explained how to use the framework. But I have never finished it to a PR-ready state.

As I noted in the HTML enhancement PR, I'd rather document both features together.

On the other hand, I would prefer integrating this so that people could use it already. In my opinion, this feature streamlines the usage of PassFailJFrame.

At the same time, the framework needs docs badly, especially as such rich features are added. And writing docs usually slips as other tasks come up.

@prrace I've just pushed documentation on how to use PassFailJFrame. It provided two samples: the new one with the builder pattern and the classic one. The samples can be copied and pasted into a file, they're ready to run, except for imports and jtreg tags.

I also submitted a bug to provide more comprehensive documentation:
JDK-8318688: Write documentation for PassFailJFrame

The windows can be positioned in advance, or a call back PositionWindows interface can be used to define their positions after the instruction UI frame is positioned on the screen.

aivanov-jdk · 2023-09-13T14:50:11Z

I've implemented the feature for adding several test UI windows.

@azvegint Could you re-review please?

The test in #15666 needed a small update as the result.

The demos for multiple windows are available in #15721. I couldn't resist to play around with a couple of layouts.

lawrence-andrew · 2023-09-13T16:58:41Z

The new several test UI windows , looks good to me.

aivanov-jdk · 2023-09-27T16:57:55Z

I submitted an enhancement JDK-8317116: Provide layouts for multiple test UI in PassFailJFrame.

openjdk-notifier · 2023-10-25T11:20:18Z

The parent pull request that this pull request depends on has now been integrated and the target branch of this pull request has been updated. This means that changes from the dependent pull request can start to show up as belonging to this pull request, which may be confusing for reviewers. To remedy this situation, simply merge the latest changes from the new target branch into this pull request by running commands similar to these in the local repository for your personal fork:

git checkout 8294156-func-manual-TestUI
git fetch https://git.openjdk.org/jdk.git master
git merge FETCH_HEAD
# if there are conflicts, follow the instructions given by git merge
git commit -m "Merge master"
git push

openjdk · 2023-10-25T11:22:54Z

@aivanov-jdk this pull request can not be integrated into master due to one or more merge conflicts. To resolve these merge conflicts and update this pull request you can run the following commands in the local repository for your personal fork:

git checkout 8294156-func-manual-TestUI
git fetch https://git.openjdk.org/jdk.git master
git merge FETCH_HEAD
# resolve conflicts and follow the instructions given by git merge
git commit -m "Merge master"
git push

openjdk · 2023-10-25T11:26:36Z

@aivanov-jdk This change now passes all automated pre-integration checks.

ℹ️ This project also has non-automated pre-integration requirements. Please see the file CONTRIBUTING.md for details.

After integration, the commit message for the final commit will be:

8294156: Allow PassFailJFrame.Builder to create test UI

Reviewed-by: azvegint, prr

You can use pull request commands such as /summary, /contributor and /issue to adjust it as needed.

At the time when this comment was updated there had been no new commits pushed to the master branch. If another commit should be pushed before you perform the /integrate command, your PR will be automatically rebased. If you prefer to avoid any potential automatic rebasing, please check the documentation for the /integrate command for further details.

➡️ To integrate this PR with the above commit message to the master branch, type /integrate in a new comment.

aivanov-jdk · 2023-10-25T11:30:06Z

/integrate

openjdk · 2023-10-25T11:31:52Z

Going to push as commit 42b9ac8.

openjdk · 2023-10-25T11:32:07Z

@aivanov-jdk Pushed as commit 42b9ac8.

💡 You may see a message that your pull request was closed with unmerged commits. This can be safely ignored.

aivanov-jdk added 13 commits September 11, 2023 12:08

Enable HTML display if instructions start with <html>

0d5343a

Instructions for FileChooserSymLinkTest are rendered in HTML.

Improve instruction formatting

db08cfc

Refactor configuration of a text component for instructions

80fec8a

Each text component (JTextArea or JEditorPane) are configured in its own dedicated method. This avoids unnecessary type casts.

Revert changes to FileChooserSymLinkTest.java

7753b3f

Wrap createUI call

c388d73

It reverts the accidental change where I unwrapped call to createUI

Refactor windowClosing listener

b78c62b

Moved it to a named class, saved the instance in a field. It's to be used with test windows.

Build functional test UI

3fc976d

The Builder now provides a method to create test UI, PassFailJFrame automatically invokes the method reference on the EDT and then shows both the instruction frame and the test window.

Use statically imported invokeAndWait and isEDT

338416f

Use functional style for disposing of windows

fd5689b

Also clean up the doc for disposeWindows().

Use invokeOnEDT in getInstructionFrameBounds

bdfc39d

Amend message in window closing handler

62a477e

The WindowClosingHandler is used both for the instruction frame and for test UI windows. Also add blank lines to separate different parts of the class.

Mark the Builder class final

37a8489

It's not supposed to be extended.

Remove trailing whitespace

70256b6

openjdk bot added the rfr Pull request is ready for review label Sep 11, 2023

openjdk bot added the client client-libs-dev@openjdk.org label Sep 11, 2023

This was referenced Sep 11, 2023

8316025: Use testUI() method of PassFailJFrame.Builder in FileChooserSymLinkTest.java #15666

Closed

8316017: Refactor timeout handler in PassFailJFrame #15668

Closed

azvegint reviewed Sep 12, 2023

View reviewed changes

azvegint approved these changes Sep 12, 2023

View reviewed changes

8294156: Allow creating several test windows

62521e3

The windows can be positioned in advance, or a call back PositionWindows interface can be used to define their positions after the instruction UI frame is positioned on the screen.

aivanov-jdk requested a review from azvegint September 13, 2023 14:36

aivanov-jdk mentioned this pull request Sep 13, 2023

8294156: Demo positioning of multiple test windows #15721

Closed

3 tasks

aivanov-jdk mentioned this pull request Sep 27, 2023

8294158: HTML formatting for PassFailJFrame instructions #15660

Closed

3 tasks

Add instructions on how to use PassFailJFrame

0be29d1

prrace approved these changes Oct 24, 2023

View reviewed changes

openjdk-notifier bot changed the base branch from pr/15660 to master October 25, 2023 11:20

openjdk bot added the merge-conflict Pull request has merge conflict with target branch label Oct 25, 2023

Merge master

eff09d0

openjdk bot added ready Pull request is ready to be integrated and removed merge-conflict Pull request has merge conflict with target branch labels Oct 25, 2023

openjdk bot added the integrated Pull request has been integrated label Oct 25, 2023

openjdk bot closed this Oct 25, 2023

openjdk bot removed ready Pull request is ready to be integrated rfr Pull request is ready for review labels Oct 25, 2023

aivanov-jdk deleted the 8294156-func-manual-TestUI branch October 25, 2023 11:32

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

8294156: Allow PassFailJFrame.Builder to create test UI #15665

8294156: Allow PassFailJFrame.Builder to create test UI #15665

aivanov-jdk commented Sep 11, 2023 •

edited by openjdk bot

Loading

bridgekeeper bot commented Sep 11, 2023

openjdk bot commented Sep 11, 2023

mlbridge bot commented Sep 11, 2023 •

edited

Loading

azvegint Sep 12, 2023

aivanov-jdk Sep 12, 2023

azvegint Sep 12, 2023

aivanov-jdk Sep 12, 2023

aivanov-jdk Sep 13, 2023

azvegint Sep 12, 2023

aivanov-jdk Sep 12, 2023

prrace Sep 20, 2023

aivanov-jdk Sep 27, 2023

aivanov-jdk Oct 23, 2023

aivanov-jdk Oct 23, 2023

aivanov-jdk commented Sep 13, 2023

lawrence-andrew commented Sep 13, 2023

aivanov-jdk commented Sep 27, 2023

openjdk-notifier bot commented Oct 25, 2023

openjdk bot commented Oct 25, 2023

openjdk bot commented Oct 25, 2023

aivanov-jdk commented Oct 25, 2023

openjdk bot commented Oct 25, 2023

openjdk bot commented Oct 25, 2023

8294156: Allow PassFailJFrame.Builder to create test UI #15665

8294156: Allow PassFailJFrame.Builder to create test UI #15665

Conversation

aivanov-jdk commented Sep 11, 2023 • edited by openjdk bot Loading

Progress

Issue

Reviewers

Reviewing

Webrev

bridgekeeper bot commented Sep 11, 2023

openjdk bot commented Sep 11, 2023

mlbridge bot commented Sep 11, 2023 • edited Loading

Webrevs

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

aivanov-jdk commented Sep 13, 2023

lawrence-andrew commented Sep 13, 2023

aivanov-jdk commented Sep 27, 2023

openjdk-notifier bot commented Oct 25, 2023

openjdk bot commented Oct 25, 2023

openjdk bot commented Oct 25, 2023

aivanov-jdk commented Oct 25, 2023

openjdk bot commented Oct 25, 2023

openjdk bot commented Oct 25, 2023

aivanov-jdk commented Sep 11, 2023 •

edited by openjdk bot

Loading

mlbridge bot commented Sep 11, 2023 •

edited

Loading