RFR: 8340466: Add description for PassFailJFrame constructors [v2]

[Alexey Ivanov]

On Tue, 24 Sep 2024 23:36:17 GMT, Harshitha Onkar <honkar at openjdk.org> wrote:

> > Shall we deprecate the constructors in favor of Builder?
> >
> > The builder provides a more streamlined experience, therefore new tests should use it instead of constructors. We may update the tests which use the constructors, after which the constructors can be removed.
> 
> There are some cases where the builder approach may not work as expected especially modal dialog tests and in such instances the older constructor methods are used.

I can't see how it's possible… Do you have an example?

The builder provides the same features as constructors do. The only difference is that builder automatically shows all the registered windows.

Just like with the `PassFailJFrame` constructors, you can do other stuff before you use builder to create an instance of `PassFailJFrame`; just like with the constructors, you can do other stuff after creating the instance and before calling `awaitAndCheck`. You can use `addTestWindow` and `positionTestWindow` during the test execution if needed.

You also can employ (window) events to start or to synchronise other parts of running the test, `LotsOfMenuItemsTest.java` is a great example of such an approach.

https://github.com/openjdk/jdk/blob/9806d2139cb5994effdee3f7bc6b23eb81858ed3/test/jdk/java/awt/MenuItem/LotsOfMenuItemsTest.java#L74-L85

I agree there could be shortcomings in the `PassFailJFrame` design where you have to write more code for an uncommon scenario. However, if the most common scenario lets you write less code, it is still a win.

-------------

PR Comment: https://git.openjdk.org/jdk/pull/21145#issuecomment-2373565416