Skip to content
GitLab
Explore
Sign in
Primary navigation
Search or go to…
Project
J
jdk17u
Manage
Activity
Members
Labels
Plan
Issues
Issue boards
Milestones
Wiki
Code
Merge requests
Repository
Branches
Commits
Tags
Repository graph
Compare revisions
Snippets
Build
Pipelines
Jobs
Pipeline schedules
Artifacts
Deploy
Releases
Package registry
Model registry
Operate
Environments
Terraform modules
Monitor
Incidents
Analyze
Value stream analytics
Contributor analytics
CI/CD analytics
Repository analytics
Model experiments
Help
Help
Support
GitLab documentation
Compare GitLab plans
Community forum
Contribute to GitLab
Provide feedback
Keyboard shortcuts
?
Snippets
Groups
Projects
Show more breadcrumbs
einsteinathome
openjdk
jdk17u
Commits
59fcc3c6
Commit
59fcc3c6
authored
6 months ago
by
Goetz Lindenmaier
Browse files
Options
Downloads
Patches
Plain Diff
8340785: Update description of PassFailJFrame and samples
Backport-of: 5063494f5b0859a396b4e41096793c777d4650b8
parent
fadfa582
Branches
Branches containing commit
Tags
Tags containing commit
No related merge requests found
Changes
1
Show whitespace changes
Inline
Side-by-side
Showing
1 changed file
test/jdk/java/awt/regtesthelpers/PassFailJFrame.java
+159
-33
159 additions, 33 deletions
test/jdk/java/awt/regtesthelpers/PassFailJFrame.java
with
159 additions
and
33 deletions
test/jdk/java/awt/regtesthelpers/PassFailJFrame.java
+
159
−
33
View file @
59fcc3c6
...
...
@@ -79,15 +79,77 @@ import static javax.swing.SwingUtilities.invokeAndWait;
import
static
javax
.
swing
.
SwingUtilities
.
isEventDispatchThread
;
/**
* Provides a framework for manual tests to display test instructions and
* Pass/Fail buttons.
* A framework for manual tests to display test instructions and
* <i>Pass</i> / <i>Fail</i> buttons. The framework automatically
* creates a frame to display the instructions, provides buttons
* to select the test result, and handles test timeout.
*
* <p id="timeOutTimer">
* The instruction UI frame displays a timer at the top which indicates
* how much time is left. The timer can be paused using the <i>Pause</i>
* button to the right of the time; the title of the button changes to
* <i>Resume</i>. To resume the timer, use the <i>Resume</i> button.
*
* <p id="instructionText">
* In the center, the instruction UI frame displays instructions for the
* tester. The instructions can be either plain text or HTML. If the
* text of the instructions starts with {@code "<html>"}, the
* instructions are displayed as HTML, as supported by Swing, which
* provides richer formatting options.
* <p>
* Instructions for the user can be either plain text or HTML as supported
* by Swing. If the instructions start with {@code <html>}, the
* instructions are displayed as HTML.
* The instructions are displayed in a text component with word-wrapping
* so that there's no horizontal scroll bar. If the text doesn't fit, a
* vertical scroll bar is shown. Use {@code rows} and {@code columns}
* parameters to change the size of this text component.
* If possible, choose the number of rows and columns so that
* the instructions fit and no scroll bars are shown.
*
* <p id="passFailButtons">
* At the bottom, the instruction UI frame displays the
* <i>Pass</i> and <i>Fail</i> buttons. The tester clicks either <i>Pass</i>
* or <i>Fail</i> button to finish the test. When the tester clicks the
* <i>Fail</i> button, the framework displays a dialog box prompting for
* a reason why the test fails. The tester enters the reason and clicks
* <i>OK</i> to close the dialog and fail the test,
* or simply closes the dialog to fail the test without providing any reason.
*
* <p id="screenCapture">
* If you enable the screenshot feature, a <i>Screenshot</i> button is
* added to the right of the <i>Fail</i> button. The tester can choose either
* <i>Capture Full Screen</i> (default) or <i>Capture Frames</i> and click the
* <i>Screenshot</i> button to take a screenshot.
* If there are multiple screens, screenshots of each screen are created.
* If the tester selects the <i>Capture Frames</i> mode, screenshots of all
* the windows or frames registered in the {@code PassFailJFrame} framework
* are created.
*
* <p id="logArea">
* If you enable a log area, the instruction UI frame adds a text component
* to display log messages below the buttons.
* Use {@link #log(String) log}, {@link #logSet(String) logSet}
* and {@link #logClear() logClear} static methods of {@code PassFailJFrame}
* to add or clear messages from the log area.
*
* <p id="awaitTestResult">
* After you create an instance of {@code PassFailJFrame}, call the
* {@link #awaitAndCheck() awaitAndCheck} method to stop the current thread
* (usually the main thread) and wait until the tester clicks
* either <i>Pass</i> or <i>Fail</i> button,
* or until the test times out.
* <p>
* The call to the {@code awaitAndCheck} method is usually the last
* statement in the {@code main} method of your test.
* If the test fails, an exception is thrown to signal the failure to jtreg.
* The test fails if the tester clicks the <i>Fail</i> button,
* if the timeout occurs,
* or if any window or frame is closed.
* <p>
* Before returning from {@code awaitAndCheck}, the framework disposes of
* all the windows and frames.
*
* <h2 id="sampleManualTest">Sample Manual Test</h2>
* A simple test would look like this:
*
<pre>{@code
*
{@snippet id='sampleManualTestCode' lang='java':
* public class SampleManualTest {
* private static final String INSTRUCTIONS =
* "Click Pass, or click Fail if the test failed.";
...
...
@@ -95,7 +157,7 @@ import static javax.swing.SwingUtilities.isEventDispatchThread;
* public static void main(String[] args) throws Exception {
* PassFailJFrame.builder()
* .instructions(INSTRUCTIONS)
* .testUI(
() ->
createTestUI
()
)
* .testUI(
SampleManualTest::
createTestUI)
* .build()
* .awaitAndCheck();
* }
...
...
@@ -106,39 +168,87 @@ import static javax.swing.SwingUtilities.isEventDispatchThread;
* return testUI;
* }
* }
* }
</pre>
* }
* <p>
* The above example uses the {@link Builder Builder} to set the parameters of
* the instruction frame. It is the recommended way.
* The above example uses the {@link Builder Builder} class to set
* the parameters of the instruction frame.
* It is <em>the recommended way</em>.
*
* <p>
* The framework will create instruction UI, it will call
* the provided {@code createTestUI} on the Event Dispatch Thread (EDT),
* and it will automatically position the test UI and make it visible.
* The framework will create an instruction UI frame, it will call
* the provided {@code createTestUI} on the Event Dispatch Thread (<dfn>EDT</dfn>),
* and it will automatically position the test UI frame and make it visible.
*
* <p id="jtregTagsForTest">
* Add the following jtreg tags before the test class declaration
* {@snippet :
* /*
* * @test
* * @summary Sample manual test
* * @library /java/awt/regtesthelpers
* * @build PassFailJFrame
* * @run main/manual SampleManualTest
* }
* and the closing comment tag <code>*/</code>.
* <p>
* The {@code @library} tag points to the location of the
* {@code PassFailJFrame} class in the source code;
* the {@code @build} tag makes jtreg compile the {@code PassFailJFrame} class,
* and finally the {@code @run} tag specifies it is a manual
* test and the class to run.
*
* <h2 id="usingBuilder">Using {@code Builder}</h2>
* Use methods of the {@link Builder Builder} class to set or change
* parameters of {@code PassFailJFrame} and its instruction UI:
* <ul>
* <li>{@link Builder#title(String) title} sets
* the title of the instruction UI
* (the default is {@value #TITLE});</li>
* <li>{@link Builder#testTimeOut(long) testTimeOut} sets
* the timeout of the test
* (the default is {@value #TEST_TIMEOUT});</li>
* <li>{@link Builder#rows(int) rows} and
* {@link Builder#columns(int) columns} control the size
* the text component which displays the instructions
* (the default number of rows is the number of lines in the text
* of the instructions,
* the default number of columns is {@value #COLUMNS});</li>
* <li>{@link Builder#logArea() logArea} adds a log area;</li>
* <li>{@link Builder#screenCapture() screenCapture}
* enables screenshots.</li>
* </ul>
*
* <h3 id="builderTestUI">Using {@code testUI} and {@code splitUI}</h3>
* The {@code Builder.testUI} methods accept interfaces which create one window
* or a list of windows if the test needs multiple windows,
* or directly a single window, an array of windows or a list of windows.
* <p>
* For simple test UI, use {@code Builder.splitUI}, or explicitly
* {@code Builder.splitUIRight} or {@code Builder.splitUIBottom} with
* a {@code PanelCreator}. The framework will call the provided
* {@code createUIPanel} to create the component with test UI and
* For simple test UI, use {@link Builder#splitUI(PanelCreator) splitUI},
* or explicitly
* {@link Builder#splitUIRight(PanelCreator) splitUIRight} or
* {@link Builder#splitUIBottom(PanelCreator) splitUIBottom} with
* a {@link PanelCreator PanelCreator}.
* The framework will call the provided
* {@code createUIPanel} method to create the component with test UI and
* will place it as the right or bottom component in a split pane
* along with instruction UI.
* <p>
* Note: <em>support for multiple windows is incomplete</em>.
*
* <h2 id="obsoleteSampleTest">Obsolete Sample Test</h2>
* Alternatively, use one of the {@code PassFailJFrame} constructors to
* create an object, then create secondary test UI, register it
* with {@code PassFailJFrame}, position it and make it visible.
* The following sample demonstrates it:
*
<pre>{@code
* public class
SampleOld
ManualTest {
*
{@snippet id='obsoleteSampleTestCode' lang='java':
* public class
Obsolete
ManualTest {
* private static final String INSTRUCTIONS =
* "Click Pass, or click Fail if the test failed.";
*
* public static void main(String[] args) throws Exception {
* PassFailJFrame passFail = new PassFailJFrame(INSTRUCTIONS);
*
* SwingUtilities.invokeAndWait(
() ->
createTestUI
()
);
* SwingUtilities.invokeAndWait(
ObsoleteManualTest::
createTestUI);
*
* passFail.awaitAndCheck();
* }
...
...
@@ -151,17 +261,29 @@ import static javax.swing.SwingUtilities.isEventDispatchThread;
* testUI.setVisible(true);
* }
* }
* }
</pre>
* }
* <p>
* Use methods of the {@code Builder} class or constructors of the
* {@code PassFailJFrame} class to control other parameters:
* <ul>
* <li>the title of the instruction UI,</li>
* <li>the timeout of the test,</li>
* <li>the size of the instruction UI via rows and columns, and</li>
* <li>to add a log area,</li>
* <li>to enable screenshots.</li>
* </ul>
* This sample uses {@link #PassFailJFrame(String) a constructor} of
* {@code PassFailJFrame} to create its instance,
* there are several overloads provided which allow changing other parameters.
* <p>
* When you use the constructors, you have to explicitly create
* your test UI window on EDT. After you create the window,
* you need to register it with the framework using
* {@link #addTestWindow(Window) addTestWindow}
* to ensure the window is disposed of when the test completes.
* Before showing the window, you have to call
* {@link #positionTestWindow(Window, Position) positionTestWindow}
* to position the test window near the instruction UI frame provided
* by the framework. And finally you have to explicitly show the test UI
* window by calling {@code setVisible(true)}.
* <p>
* To avoid the complexity, use the {@link Builder Builder} class
* which provides a streamlined way to configure and create an
* instance of {@code PassFailJFrame}.
* <p>
* Consider updating tests which use {@code PassFailJFrame} constructors to
* use the builder pattern.
*/
public
final
class
PassFailJFrame
{
...
...
@@ -541,7 +663,11 @@ public final class PassFailJFrame {
:
configurePlainText
(
instructions
,
rows
,
columns
);
text
.
setEditable
(
false
);
main
.
add
(
new
JScrollPane
(
text
),
BorderLayout
.
CENTER
);
JPanel
textPanel
=
new
JPanel
(
new
BorderLayout
());
textPanel
.
setBorder
(
createEmptyBorder
(
4
,
0
,
0
,
0
));
textPanel
.
add
(
new
JScrollPane
(
text
),
BorderLayout
.
CENTER
);
main
.
add
(
textPanel
,
BorderLayout
.
CENTER
);
JButton
btnPass
=
new
JButton
(
"Pass"
);
btnPass
.
addActionListener
((
e
)
->
{
...
...
@@ -822,7 +948,7 @@ public final class PassFailJFrame {
private
static
JComponent
createCapturePanel
()
{
JComboBox
<
CaptureType
>
screenShortType
=
new
JComboBox
<>(
CaptureType
.
values
());
JButton
capture
=
new
JButton
(
"Screen
S
hot"
);
JButton
capture
=
new
JButton
(
"Screen
s
hot"
);
capture
.
addActionListener
((
e
)
->
captureScreen
((
CaptureType
)
screenShortType
.
getSelectedItem
()));
...
...
@@ -834,7 +960,7 @@ public final class PassFailJFrame {
private
enum
CaptureType
{
FULL_SCREEN
(
"Capture Full Screen"
),
WINDOWS
(
"Capture
Individual
Frame"
);
WINDOWS
(
"Capture Frame
s
"
);
private
final
String
type
;
CaptureType
(
String
type
)
{
...
...
This diff is collapsed.
Click to expand it.
Preview
0%
Loading
Try again
or
attach a new file
.
Cancel
You are about to add
0
people
to the discussion. Proceed with caution.
Finish editing this message first!
Save comment
Cancel
Please
register
or
sign in
to comment