Form authentication – Custom script basics and examples
This document provides a comprehensive overview of custom scripting for web application automation. It outlines the fundamental concepts, key functions, and best practices needed to implement scripts effectively. Additionally, it includes practical examples of the most commonly used scripts to facilitate authentication and interaction within the form authentication script editor.
By following this guide, you will gain a structured understanding of how to leverage custom scripts to optimize and streamline your automation processes.
Custom script basics
Element Path
The element path refers to the CSS selector for a specific element. This can be a full path or a more direct reference, such as an ID. Since an ID is unique within a webpage, it is a reliable way to locate a specific element.
To manually retrieve a selector in Google Chrome:
- Right-click the desired element.
- Select "Inspect" to open the Developer Tools.
- The element will be highlighted in the Elements panel. Right-click it and choose Copy > Copy selector.
- Paste the copied selector into the function, ensuring it is enclosed in quotes.
NOTE: The Custom Script Editor defaults to using the optimized CSS path, prioritizing the nearest ID and its relative path. However, after clicking ‘Test Script’, it switches to generating full paths. To reset this behavior, either close and reopen the editor or click “Load Login Form” in the upper left corner. |
Value to Enter
This applies when setting a value. The tool typically determines whether to use a username or password based on the active persona in the Form Authentication page. Alternatively, you can manually enter a custom value by passing it as a quoted string.
This is especially useful for additional fields beyond username and password, such as location or timezone selections.
Delay
You can optionally specify a delay (in milliseconds) for any function.
IMPORTANT: This delay starts when the script begins, rather than after the previous command. |
Delays may be necessary in cases where:
- A webpage includes loading animations.
- A brief wait is required before the login button becomes active after entering credentials.
Example scripts
Setting values in fields
Insert text into fields
This is the main function for inserting text into fields. It is useful when fields do not have IDs but can be selected via CSS/XPath.
netsparker.auth.setValueByQuery([element path], [value to enter], [delay in ms (opt.)]); |
Example:
netsparker.auth.setValueByQuery('input[name="username"]', 'testuser', 1000); |
Set Input Field by ID
Works like setValueByQuery, but specifically for <input> elements with IDs. Might be more reliable if an element has a unique ID.
netsparker.auth.setInputValue([element id], [value]); |
Example:
netsparker.auth.setInputValue('password-field', 'mypassword'); |
Enter text via keypress
This script simulates keypresses instead of directly setting values. It is useful when regular methods fail (e.g., JavaScript frameworks that require user input events).
netsparker.auth.setValueByKeyPress('[element id]', username); |
Example:
netsparker.auth.setValueByKeyPress('username-field', 'testuser'); |
Clicking buttons
Simulate Click on Element
This script simulates a button click.
netsparker.auth.clickByQuery([element path], [delay in ms (opt.)]); |
Example:
netsparker.auth.clickByQuery('button[type="submit"]', 500); |
Trigger Click by ID
Similar to clickByQuery, but targets elements by ID.
netsparker.auth.click([element id]); |
Example:
netsparker.auth.click('login-btn'); |
Automated login handling
Perform Login
A built-in function that automatically detects username/password fields and fills them. Best for simple login forms without complex scripts.
netsparker.auth.login(username, password); |
Example:
netsparker.auth.login('testuser', 'mypassword'); |
Interacting with frames
Perform Action in Iframe
Likely used for interacting with elements inside iframes.
netsparker.auth.executeInFrame(document.querySelectorAll([element path], ' + [value] + ');'); |
Example (if the login form is inside an iframe):
netsparker.auth.executeInFrame( (function() { const usernameField = document.querySelector('input[name="username"]'); if (usernameField) { usernameField.value = 'test'; } })() ); |
When to use which?
Function | Use Case |
setValueByQuery | General field population (by CSS selector) |
setInputValue | Setting input values by ID |
setValueByKeyPress | When fields require simulated keypresses |
clickByQuery | Clicking buttons (by CSS selector) |
click | Clicking buttons (by ID) |
login | Automated login detection |
executeInFrame | Handling login inside iframes |