#JMeter Plugin

The Webswing JMeter Plugin allows you to perform automated load testing of Java Swing applications running in Webswing. This plugin provides samplers that can connect to Webswing applications via WebSocket and simulate user interactions.

#Installation

#Prerequisites

• Apache JMeter 5.6.3 or later
• Running Webswing server with your Java Swing application
• Access to Webswing JWT secret from webswing.properties for authentication

#Installing the Plugin

1. Download JMeter:

   • Download Apache JMeter from the official site: https://jmeter.apache.org/download_jmeter.cgi
   • Extract JMeter to your desired location

2. Install JMeter Plugins Manager (Optional but recommended):

   • Download from: https://jmeter-plugins.org/wiki/PluginsManager/
   • Place .jar in your JMeter's lib/ext/ directory

3. Install Webswing JMeter Plugin:

   • The Webswing JMeter Plugin is included in the test-tools distribution
   • Find the plugin jar at: jmeter/plugin/webswing_jmeter_plugin-{version}.jar
   • Copy this jar file to your JMeter's lib/ext/ directory

4. Verify Installation:

   • Start JMeter GUI
   • Right-click on Thread Group → Add → Sampler
   • You should see three new Webswing samplers available:
     • Webswing Open WebSocket
     • Webswing Action Sampler
     • Webswing Close WebSocket

#Plugin Distribution

The Webswing JMeter Plugin is automatically included in the test-tools distribution starting from version 25.2. The plugin jar file is located in the jmeter/plugin/ directory of the test-tools zip package.

Distribution Contents:

webswing-test-tool-{version}-distribution.zip
├── jmeter/
│   ├── plugin/
│   │   └── webswing_jmeter_plugin-{version}.jar  ← Plugin jar file
│   ├── Examples/
│   │   ├── ModernisationDemo.jmx
│   │   └── WebswingDemo.jmx
│   ├── README.md
│   └── QuerySyntax.md
├── server/
├── testtool.bat
├── testtool.sh
└── webswing-test-tool.war

#Quick Start

Basic Test Plan Setup

1. Create a new Test Plan in JMeter
2. Add a Thread Group
3. Add Webswing samplers in this order:
   • Webswing Open WebSocket (to establish connection)
   • Webswing Action Sampler(s) (to perform actions - any number of them)
   • Webswing Close WebSocket (to cleanup)
4. Enable Test Mode in your application

#Plugin Components

#1. Webswing Open WebSocket Sampler

Purpose: Establishes a WebSocket connection to the Webswing application.

Key Properties:

• Protocol: ws:// or wss:// (secure WebSocket)
• URL: Full WebSocket URL to your Webswing application
• Connection Timeout: Maximum time to wait for connection (default: 15000ms)
• JWT Secret: Authentication secret (required)
• Has Third Party Security Module: Enable if using external authentication
• Start Recording: Enable to record user interactions for playback (use only in single-user mode to check if test runs correctly)

#2. Webswing Action Sampler

Purpose: Performs user interactions with the Swing application.

Action Types:

• click: Click on UI elements. Select the mouse button with WebswingAction.mouse.button (left, right, or middle).
• type: Type text into input fields, including special keys using {ENTER} style tokens.
• mouseWheel: Scroll with the mouse wheel.
• performAction: Execute custom application actions (requires action name and optional data).
• windowEvent: Window management operations including:
  • resize: Change window dimensions (requires width/height parameters)
  • close: Close the window
  • focus: Give focus to the window
  • maximize: Maximize the window
  • restore: Restore window from maximized state
  • undecorate: Remove window decorations (title bar, borders)
  • decorate: Add window decorations back
  • undock: Undock the window from its container
  • undockHidden: Undock window in hidden state
  • dock: Dock the window back to container
  • forceDock: Force dock the window
  • toFront: Bring window to front
  • checkTabClose: Check if tab can be closed
  • updateTabPosition: Update tab position
  • deactivateAll: Deactivate all windows
  • dispose: Dispose the window resources
  • renderInTab: Render window in tab mode
• checkValue: Verify component value matches expected.
• isExists: Check if element exists.
• isNotExists: Verify element does not exist.
• getElement: Retrieve element information.

Window Action Targeting Logic:

Window events can target windows in two ways:

1. Element-based targeting (when query is provided):

   • The plugin finds the specified UI element using the query
   • Extracts the windowId from the element's window
   • Sends the window event to that specific window
   • Use this when you want to target a specific window containing a known element

2. Last-known window targeting (when query is empty):

   • Uses the most recently discovered windowId from previous component tree requests
   • The windowId is automatically tracked and updated during element searches
   • Sends the window event to this cached window
   • Use this for general window operations when you don't need to target a specific element

WindowId Management:

• The windowId is automatically obtained from the root component when the WebSocket connection is established
• It gets updated whenever element searches are performed (from component tree responses)
• The plugin maintains this windowId in memory throughout the test session
• No manual windowId management is required from the user

Usage Examples:

<!-- Target specific window containing a button -->
<stringProp name="actionType">windowEvent</stringProp>
<stringProp name="windowEventType">maximize</stringProp>
<stringProp name="query">JButton[name="myButton"]</stringProp>

<!-- Target last-known window (no query needed) -->
<stringProp name="actionType">windowEvent</stringProp>
<stringProp name="windowEventType">close</stringProp>
<stringProp name="query"></stringProp>

#3. Webswing Close WebSocket Sampler

Purpose: Properly closes the WebSocket connection and cleans up resources.

#Configuration

#Connection Configuration

# Basic Connection Settings
Protocol: ws://
URL: ws://localhost:8080/your-app-name
Connection Timeout: 15000
JWT Secret: your_jwt_secret_here

# Security Settings
Has Third Party Security Module: false

# Recording Settings
Start Recording: false

#User Authentication

For multiple users, use CSV Data Set Config:

users.csv:

USERNAME,PASSWORD
user1,pass1
user2,pass2
user3,pass3

If users are not defined, the plugin will create usernames based on thread number. (JMeter + threadId)

CSV Data Set Config:

• Filename: path/to/users.csv
• Variable Names: USERNAME,PASSWORD
• Delimiter: ,
• Recycle on EOF: true
• Stop thread on EOF: false

#Common Issues

#Connection Problems

Error: "WebSocket connection failed"

Solutions:

• Verify Webswing server is running
• Check WebSocket URL format
• Ensure JWT secret is correct

Error: "Connection timeout"

Solutions:

• Increase connection timeout value
• Check server capacity under load
• Verify application startup time

#Element Not Found

Error: "Element not found"

Solutions:

• Verify element selector syntax
• Check if element exists at execution time
• Increase search timeout
• Use View Results Tree to debug

#Authentication Issues

Error: "Authentication failed"

Solutions:

• Verify JWT secret matches server configuration
• Check third-party security module settings

#Debug Mode

Enable JMeter debug logging (info/debug/trace):

# Add to log4j2.xml in JMeter's bin directory
<Logger name="org.webswing.tools.jmeter.plugin" level="debug_level" additivity="false">
<AppenderRef ref="jmeter-log"/>
<AppenderRef ref="gui-log-event"/>
</Logger>

#Recording and Playback

Recording Mode (Development/Debugging Only):

• Enable "Start Recording" in WebSocket Open sampler
• Perform manual actions in the application
• Recording captures all user interactions
• Important: Only use in single-user mode for test creation

#Command Line Execution

For load testing, it is recommended to run JMeter in non-GUI (CLI) mode, GUI mode is only for test creation and debugging.

# Basic execution
jmeter -n -t webswing-test.jmx -l results.jtl

# With custom properties
jmeter -n -t webswing-test.jmx -l results.jtl -Jusers=100 -Jrampup=300

# Generate HTML report
jmeter -n -t webswing-test.jmx -l results.jtl -e -o report-folder

#WebSocket Open Sampler Properties

Property	Type	Default	Description
protocol	String	ws://	WebSocket protocol (ws:// or wss://)
url	String	-	Full WebSocket URL
connectionTimeout	Long	15000	Connection timeout in milliseconds
jwtSecret	String	-	JWT authentication secret (required)
hasThirdPartySecurityModule	Boolean	false	Enable third-party authentication
startRecording	Boolean	false	Start recording user interactions

#Action Sampler Properties

Property	Description	Default
actionType	Type of action to perform (click, type, mouseWheel, windowEvent, performAction, etc.)	(required)
actionName	Name for the action (used for reporting or custom actions)
query	UI element selector (componentType, name, value, etc.)
input	Input value for the action (used by type or performAction)
timeout	Max time to wait for action (ms - e.g. find an element)	10000
executionDelay	Wait before action (ms)	0 (no delay)
clearText	Clear field before typing (true/false)	false
performActionName	Name of custom action to perform
performActionData	Data for custom action
waitForActionName	Name of action to wait for (used in waitFor)
waitForActionTimeout	Timeout for waitFor action (ms)
windowEventWidth	Width for windowEvent "Resize" action
windowEventHeight	Height for windowEvent "Resize" action
windowEventType	Type of window event (resize, close, focus, etc.)
mouseWheelScrollAmount	Scroll amount for mouseWheel actions
mouseButton	Mouse button for click actions (left, right, middle)	left
value	Value for certain actions (e.g., set value)

#Notes

• Use only the properties relevant to the actionType you select.
• Unused properties can be left blank.

#Action Types

Action Type	Description	Required Properties	Optional Properties
click	Mouse click on UI elements	query	mouseButton, executionDelay, timeout
type	Type text into input fields	query, input	clearText, executionDelay, timeout
mouseWheel	Scroll using mouse wheel	query	mouseWheelScrollAmount, executionDelay, timeout
windowEvent	Window management operations	(varies by event type)	windowEventWidth, windowEventHeight (for resize only)
performAction	Execute custom application actions	performActionName	performActionData, waitForActionName, waitForActionTimeout
checkValue	Verify component value matches expected	query, value	executionDelay, timeout
isExists	Check if element exists	query	executionDelay, timeout
isNotExists	Verify element does not exist	query	executionDelay, timeout
getElement	Retrieve element information	query	executionDelay, timeout

#Component Tree Discovery

Component Tree Discovery is the process of identifying UI elements in your Swing application so you can interact with them in your JMeter tests. Think of it as "inspecting" the application's UI structure to find the names, properties, and attributes of buttons, text fields, tables, and other components.

#Enabling Test Mode

Before you can discover components, you must enable Test Mode in your Webswing application:

#Method 1: Via Configuration File

# In webswing.config under your desired application section
"testMode"=true

#Method 2: Via Admin Console

1. Open Webswing Admin Console in your browser
2. Navigate to your application configuration
3. Find the "Test Mode" option and enable it
4. Save the updated configuration

#Discovering UI Components

#Step 1: Open Browser Developer Tools

1. Open your Webswing application in a web browser
2. Open developer tools and navigate to the Console tab

#Step 2: Execute Component Tree Query

Run this JavaScript command in the console:

// Get complete component tree
webswingInstance0.requestComponentTree().then((tree)=>console.log(tree))

#Step 3: Analyze the Output

The command will output a JSON structure showing all UI components. Each component includes properties like:

{
  "componentType": "JButton",
  "name": "submitButton", 
  "value": "Submit",
  "enabled": true,
  "visible": true,
  "width": 100,
  "height": 30,
  "screenx": 150,
  "screeny": 200,
  "selected": false
}

#Query Syntax Reference

For complete query syntax documentation, see JMeter Query Syntax.

Quick Reference:

• Component types: JButton, JTextField, JLabel, JTable, etc.
• Operators: = (exact), *= (contains), ^= (starts with), $= (ends with)
• Combinators: "space" (descendant), > (child), + (adjacent sibling)

#Example Files

The plugin includes example files:

• ModernisationDemo.jmx: Complete test plan example
• WebswingDemo.jmx: Basic test plan example

#Version Compatibility

• Webswing: 25.2 and later
• JMeter: 5.6.3 and later