0
# Form Interaction
1

2
Comprehensive form automation capabilities including field input, selection handling, file uploads, and form submission. Essential for login automation, data entry workflows, and web application testing.
3

4
## Capabilities
5

6
### HtmlForm Class
7

8
Primary interface for form manipulation and submission.
9

10
```java { .api }
11
/**
12
 * HTML form element with submission and field management
13
 */
14
public class HtmlForm extends HtmlElement {
15
    /** Submit form using default submit button */
16
    public <P extends Page> P submit() throws IOException;
17
    
18
    /** Submit form using specific submit element */
19
    public <P extends Page> P submit(SubmittableElement submitElement) throws IOException;
20
    
21
    /** Reset form to default values */
22
    public void reset();
23
    
24
    /** Get form method (GET/POST) */
25
    public String getMethodAttribute();
26
    
27
    /** Get form action URL */
28
    public String getActionAttribute();
29
    
30
    /** Get form encoding type */
31
    public String getEnctypeAttribute();
32
    
33
    /** Get form target */
34
    public String getTargetAttribute();
35
    
36
    /** Get input element by name */
37
    public HtmlElement getInputByName(String name);
38
    
39
    /** Get all input elements by name */
40
    public List<HtmlElement> getInputsByName(String name);
41
    
42
    /** Get text input by value */
43
    public HtmlTextInput getInputByValue(String value);
44
    
45
    /** Get elements by tag name within form */
46
    public List<HtmlElement> getHtmlElementsByTagName(String tagName);
47
    
48
    /** Get select element by name */
49
    public HtmlSelect getSelectByName(String name);
50
    
51
    /** Get all select elements by name */
52
    public List<HtmlSelect> getSelectsByName(String name);
53
    
54
    /** Get textarea by name */
55
    public HtmlTextArea getTextAreaByName(String name);
56
    
57
    /** Get button by name */
58
    public HtmlButton getButtonByName(String name);
59
    
60
    /** Check if form accepts file uploads */
61
    public boolean isMultiPartForm();
62
    
63
    /** Get form's character set */
64
    public String getAcceptCharsetAttribute();
65
    
66
    /** Check if form validation is disabled */
67
    public boolean isNoValidate();
68
}
69
```
70

71
**Usage Examples:**
72

73
```java
74
import com.gargoylesoftware.htmlunit.html.*;
75

76
try (WebClient webClient = new WebClient()) {
77
    HtmlPage page = webClient.getPage("https://example.com/login");
78
    
79
    // Find and fill login form
80
    HtmlForm loginForm = page.getFormByName("loginForm");
81
    
82
    HtmlTextInput usernameField = loginForm.getInputByName("username");
83
    usernameField.setValueAttribute("john.doe");
84
    
85
    HtmlPasswordInput passwordField = (HtmlPasswordInput) loginForm.getInputByName("password");
86
    passwordField.setValueAttribute("secretpassword");
87
    
88
    HtmlCheckBoxInput rememberMe = (HtmlCheckBoxInput) loginForm.getInputByName("remember");
89
    rememberMe.setChecked(true);
90
    
91
    // Submit form
92
    HtmlSubmitInput submitButton = (HtmlSubmitInput) loginForm.getInputByName("submit");
93
    HtmlPage resultPage = submitButton.click();
94
    
95
    // Or submit directly
96
    HtmlPage resultPage2 = loginForm.submit();
97
}
98
```
99

100
### HtmlInput Class
101

102
Base class for all HTML input elements.
103

104
```java { .api }
105
/**
106
 * Base class for HTML input elements
107
 */
108
public abstract class HtmlInput extends HtmlElement implements SubmittableElement, DisabledElement {
109
    /** Get input type attribute */
110
    public String getTypeAttribute();
111
    
112
    /** Get input value */
113
    public String getValueAttribute();
114
    
115
    /** Set input value */
116
    public void setValueAttribute(String value);
117
    
118
    /** Get input name */
119
    public String getNameAttribute();
120
    
121
    /** Get default value */
122
    public String getDefaultValue();
123
    
124
    /** Set default value */
125
    public void setDefaultValue(String defaultValue);
126
    
127
    /** Check if input is disabled */
128
    public boolean isDisabled();
129
    
130
    /** Set disabled state */
131
    public void setDisabled(boolean disabled);
132
    
133
    /** Check if input is read-only */
134
    public boolean isReadOnly();
135
    
136
    /** Set read-only state */
137
    public void setReadOnly(boolean readOnly);
138
    
139
    /** Check if input is required */
140
    public boolean isRequired();
141
    
142
    /** Get input size attribute */
143
    public String getSizeAttribute();
144
    
145
    /** Get maxlength attribute */
146
    public String getMaxLengthAttribute();
147
    
148
    /** Get placeholder text */
149
    public String getPlaceholderAttribute();
150
    
151
    /** Check if input has focus */
152
    public boolean hasFocus();
153
    
154
    /** Select all text in input */
155
    public void select();
156
    
157
    /** Get form containing this input (if any) */
158
    public HtmlForm getEnclosingForm();
159
    
160
    /** Check if input value is valid */
161
    public boolean isValid();
162
    
163
    /** Get validation message */
164
    public String getValidationMessage();
165
    
166
    /** Check validity and show validation message */
167
    public boolean checkValidity();
168
    
169
    /** Set custom validation message */
170
    public void setCustomValidity(String message);
171
}
172
```
173

174
### Text Input Elements
175

176
```java { .api }
177
/**
178
 * Single-line text input (<input type="text">)
179
 */
180
public class HtmlTextInput extends HtmlInput {
181
    /** Type text into field (fires events) */
182
    public void type(String text) throws IOException;
183
    
184
    /** Append text to existing value */
185
    public void appendText(String text) throws IOException;
186
    
187
    /** Clear the input field */
188
    public void clear();
189
    
190
    /** Get text selection start position */
191
    public int getSelectionStart();
192
    
193
    /** Get text selection end position */
194
    public int getSelectionEnd();
195
    
196
    /** Set text selection range */
197
    public void setSelectionRange(int start, int end);
198
}
199

200
/**
201
 * Password input (<input type="password">)
202
 */
203
public class HtmlPasswordInput extends HtmlInput {
204
    /** Type password text (fires events) */
205
    public void type(String text) throws IOException;
206
    
207
    /** Clear password field */
208
    public void clear();
209
}
210

211
/**
212
 * Hidden input (<input type="hidden">)
213
 */
214
public class HtmlHiddenInput extends HtmlInput {
215
    // Hidden inputs have same base functionality as HtmlInput
216
}
217

218
/**
219
 * Email input (<input type="email">)
220
 */
221
public class HtmlEmailInput extends HtmlInput {
222
    /** Type email text (fires events) */
223
    public void type(String text) throws IOException;
224
    
225
    /** Get list attribute for datalist */
226
    public String getListAttribute();
227
}
228

229
/**
230
 * Number input (<input type="number">)
231
 */
232
public class HtmlNumberInput extends HtmlInput {
233
    /** Get min value */
234
    public String getMinAttribute();
235
    
236
    /** Get max value */
237
    public String getMaxAttribute();
238
    
239
    /** Get step value */
240
    public String getStepAttribute();
241
    
242
    /** Step up by specified amount */
243
    public void stepUp(int n);
244
    
245
    /** Step down by specified amount */
246
    public void stepDown(int n);
247
}
248

249
/**
250
 * URL input (<input type="url">)
251
 */
252
public class HtmlUrlInput extends HtmlInput {
253
    /** Type URL text (fires events) */
254
    public void type(String text) throws IOException;
255
}
256

257
/**
258
 * Search input (<input type="search">)
259
 */
260
public class HtmlSearchInput extends HtmlInput {
261
    /** Type search text (fires events) */
262
    public void type(String text) throws IOException;
263
}
264

265
/**
266
 * Telephone input (<input type="tel">)
267
 */
268
public class HtmlTelephoneInput extends HtmlInput {
269
    /** Type telephone text (fires events) */
270
    public void type(String text) throws IOException;
271
}
272
```
273

274
### Button and Submit Elements
275

276
```java { .api }
277
/**
278
 * Submit button (<input type="submit">)
279
 */
280
public class HtmlSubmitInput extends HtmlInput {
281
    /** Click to submit form */
282
    public <P extends Page> P click() throws IOException;
283
    
284
    /** Get form value sent when this button submits */
285
    public String getValueAttribute();
286
}
287

288
/**
289
 * Generic button (<input type="button">)
290
 */
291
public class HtmlButtonInput extends HtmlInput {
292
    /** Click button (fires events) */
293
    public <P extends Page> P click() throws IOException;
294
}
295

296
/**
297
 * Reset button (<input type="reset">)
298
 */
299
public class HtmlResetInput extends HtmlInput {
300
    /** Click to reset form */
301
    public <P extends Page> P click() throws IOException;
302
}
303

304
/**
305
 * Image button (<input type="image">)
306
 */
307
public class HtmlImageInput extends HtmlInput {
308
    /** Click image button */
309
    public <P extends Page> P click() throws IOException;
310
    
311
    /** Click at specific coordinates */
312
    public <P extends Page> P click(int x, int y) throws IOException;
313
    
314
    /** Get image source URL */
315
    public String getSrcAttribute();
316
    
317
    /** Get image alt text */
318
    public String getAltAttribute();
319
}
320

321
/**
322
 * Button element (<button>)
323
 */
324
public class HtmlButton extends HtmlElement implements SubmittableElement, DisabledElement {
325
    /** Click button */
326
    public <P extends Page> P click() throws IOException;
327
    
328
    /** Get button type (submit/button/reset) */
329
    public String getTypeAttribute();
330
    
331
    /** Get button name */
332
    public String getNameAttribute();
333
    
334
    /** Get button value */
335
    public String getValueAttribute();
336
    
337
    /** Check if disabled */
338
    public boolean isDisabled();
339
    
340
    /** Set disabled state */
341
    public void setDisabled(boolean disabled);
342
    
343
    /** Get form containing button */
344
    public HtmlForm getEnclosingForm();
345
}
346
```
347

348
### Checkbox and Radio Elements
349

350
```java { .api }
351
/**
352
 * Checkbox input (<input type="checkbox">)
353
 */
354
public class HtmlCheckBoxInput extends HtmlInput {
355
    /** Check if checkbox is checked */
356
    public boolean isChecked();
357
    
358
    /** Set checked state */
359
    public void setChecked(boolean checked);
360
    
361
    /** Get checkbox value when checked */
362
    public String getValueAttribute();
363
    
364
    /** Check if checkbox is indeterminate */
365
    public boolean isIndeterminate();
366
    
367
    /** Set indeterminate state */
368
    public void setIndeterminate(boolean indeterminate);
369
    
370
    /** Click to toggle checked state */
371
    public <P extends Page> P click() throws IOException;
372
}
373

374
/**
375
 * Radio button (<input type="radio">)
376
 */
377
public class HtmlRadioButtonInput extends HtmlInput {
378
    /** Check if radio button is selected */
379
    public boolean isChecked();
380
    
381
    /** Set selected state (unselects others in group) */
382
    public void setChecked(boolean checked);
383
    
384
    /** Get radio button value */
385
    public String getValueAttribute();
386
    
387
    /** Click to select this radio button */
388
    public <P extends Page> P click() throws IOException;
389
    
390
    /** Get other radio buttons in same group */
391
    public List<HtmlRadioButtonInput> getRadioGroup();
392
}
393
```
394

395
### File Upload Element
396

397
```java { .api }
398
/**
399
 * File upload input (<input type="file">)
400
 */
401
public class HtmlFileInput extends HtmlInput {
402
    /** Set files to upload */
403
    public void setFiles(File... files);
404
    
405
    /** Set file data directly */
406
    public void setData(byte[] data);
407
    
408
    /** Set file with specific filename and content type */
409
    public void setContentType(String contentType);
410
    
411
    /** Get uploaded files */
412
    public File[] getFiles();
413
    
414
    /** Check if multiple files allowed */
415
    public boolean isMultiple();
416
    
417
    /** Get accepted file types */
418
    public String getAcceptAttribute();
419
    
420
    /** Clear selected files */
421
    public void clearFiles();
422
}
423
```
424

425
**Usage Examples:**
426

427
```java
428
// File upload
429
HtmlFileInput fileInput = (HtmlFileInput) form.getInputByName("attachment");
430
File uploadFile = new File("/path/to/document.pdf");
431
fileInput.setFiles(uploadFile);
432

433
// Multiple file upload
434
File[] files = {
435
    new File("/path/file1.jpg"),
436
    new File("/path/file2.png")
437
};
438
fileInput.setFiles(files);
439

440
// Direct data upload
441
byte[] fileData = "file content".getBytes();
442
fileInput.setData(fileData);
443
fileInput.setContentType("text/plain");
444
```
445

446
### Select and Option Elements
447

448
```java { .api }
449
/**
450
 * Select dropdown (<select>)
451
 */
452
public class HtmlSelect extends HtmlElement implements SubmittableElement, DisabledElement {
453
    /** Get all option elements */
454
    public List<HtmlOption> getOptions();
455
    
456
    /** Get currently selected options */
457
    public List<HtmlOption> getSelectedOptions();
458
    
459
    /** Get option by value attribute */
460
    public HtmlOption getOptionByValue(String value);
461
    
462
    /** Get option by display text */
463
    public HtmlOption getOptionByText(String text);
464
    
465
    /** Get option at index */
466
    public HtmlOption getOption(int index);
467
    
468
    /** Set option selected by value */
469
    public void setSelectedAttribute(String value, boolean selected);
470
    
471
    /** Set option selected by index */
472
    public void setSelectedIndex(int index);
473
    
474
    /** Check if multiple selection is enabled */
475
    public boolean isMultipleSelectEnabled();
476
    
477
    /** Get select name */
478
    public String getNameAttribute();
479
    
480
    /** Get select size (visible options) */
481
    public String getSizeAttribute();
482
    
483
    /** Check if disabled */
484
    public boolean isDisabled();
485
    
486
    /** Set disabled state */
487
    public void setDisabled(boolean disabled);
488
    
489
    /** Check if required */
490
    public boolean isRequired();
491
    
492
    /** Get form containing select */
493
    public HtmlForm getEnclosingForm();
494
    
495
    /** Clear all selections */
496
    public void clearSelection();
497
}
498

499
/**
500
 * Option element (<option>)
501
 */
502
public class HtmlOption extends HtmlElement {
503
    /** Check if option is selected */
504
    public boolean isSelected();
505
    
506
    /** Set selected state */
507
    public void setSelected(boolean selected);
508
    
509
    /** Get option value */
510
    public String getValueAttribute();
511
    
512
    /** Get option display text */
513
    public String getText();
514
    
515
    /** Check if option is disabled */
516
    public boolean isDisabled();
517
    
518
    /** Set disabled state */
519
    public void setDisabled(boolean disabled);
520
    
521
    /** Get option index in select */
522
    public int getIndex();
523
    
524
    /** Click to select option */
525
    public <P extends Page> P click() throws IOException;
526
}
527

528
/**
529
 * Option group (<optgroup>)
530
 */
531
public class HtmlOptionGroup extends HtmlElement {
532
    /** Get group label */
533
    public String getLabel();
534
    
535
    /** Check if group is disabled */
536
    public boolean isDisabled();
537
    
538
    /** Get options in this group */
539
    public List<HtmlOption> getOptions();
540
}
541
```
542

543
**Usage Examples:**
544

545
```java
546
// Select dropdown manipulation
547
HtmlSelect countrySelect = form.getSelectByName("country");
548

549
// Select by value
550
countrySelect.setSelectedAttribute("US", true);
551

552
// Select by text
553
HtmlOption canadaOption = countrySelect.getOptionByText("Canada");
554
canadaOption.setSelected(true);
555

556
// Multiple selection
557
HtmlSelect skillsSelect = form.getSelectByName("skills");
558
if (skillsSelect.isMultipleSelectEnabled()) {
559
    skillsSelect.setSelectedAttribute("java", true);
560
    skillsSelect.setSelectedAttribute("python", true);
561
    skillsSelect.setSelectedAttribute("javascript", true);
562
}
563

564
// Get selected values
565
List<HtmlOption> selected = countrySelect.getSelectedOptions();
566
for (HtmlOption option : selected) {
567
    System.out.println("Selected: " + option.getValueAttribute());
568
}
569
```
570

571
### TextArea Element
572

573
```java { .api }
574
/**
575
 * Multi-line text area (<textarea>)
576
 */
577
public class HtmlTextArea extends HtmlElement implements SubmittableElement, DisabledElement {
578
    /** Get textarea text content */
579
    public String getText();
580
    
581
    /** Set textarea text content */
582
    public void setText(String text);
583
    
584
    /** Get textarea name */
585
    public String getNameAttribute();
586
    
587
    /** Get number of rows */
588
    public int getRows();
589
    
590
    /** Get number of columns */
591
    public int getCols();
592
    
593
    /** Check if disabled */
594
    public boolean isDisabled();
595
    
596
    /** Set disabled state */
597
    public void setDisabled(boolean disabled);
598
    
599
    /** Check if read-only */
600
    public boolean isReadOnly();
601
    
602
    /** Set read-only state */
603
    public void setReadOnly(boolean readOnly);
604
    
605
    /** Check if required */
606
    public boolean isRequired();
607
    
608
    /** Get maximum length */
609
    public String getMaxLengthAttribute();
610
    
611
    /** Get placeholder text */
612
    public String getPlaceholderAttribute();
613
    
614
    /** Type text (fires events) */
615
    public void type(String text) throws IOException;
616
    
617
    /** Select all text */
618
    public void select();
619
    
620
    /** Get form containing textarea */
621
    public HtmlForm getEnclosingForm();
622
    
623
    /** Get text selection start */
624
    public int getSelectionStart();
625
    
626
    /** Get text selection end */
627
    public int getSelectionEnd();
628
    
629
    /** Set selection range */
630
    public void setSelectionRange(int start, int end);
631
}
632
```
633

634
### Date and Time Input Elements
635

636
```java { .api }
637
/**
638
 * Date input (<input type="date">)
639
 */
640
public class HtmlDateInput extends HtmlInput {
641
    /** Get min date */
642
    public String getMinAttribute();
643
    
644
    /** Get max date */
645
    public String getMaxAttribute();
646
    
647
    /** Get step attribute */
648
    public String getStepAttribute();
649
    
650
    /** Step up by specified amount */
651
    public void stepUp(int n);
652
    
653
    /** Step down by specified amount */
654
    public void stepDown(int n);
655
}
656

657
/**
658
 * Time input (<input type="time">)
659
 */
660
public class HtmlTimeInput extends HtmlInput {
661
    /** Get min time */
662
    public String getMinAttribute();
663
    
664
    /** Get max time */
665
    public String getMaxAttribute();
666
    
667
    /** Get step attribute */
668
    public String getStepAttribute();
669
    
670
    /** Step up by specified amount */
671
    public void stepUp(int n);
672
    
673
    /** Step down by specified amount */
674
    public void stepDown(int n);
675
}
676

677
/**
678
 * DateTime-local input (<input type="datetime-local">)
679
 */
680
public class HtmlDateTimeLocalInput extends HtmlInput {
681
    /** Get min datetime */
682
    public String getMinAttribute();
683
    
684
    /** Get max datetime */
685
    public String getMaxAttribute();
686
    
687
    /** Get step attribute */
688
    public String getStepAttribute();
689
    
690
    /** Step up by specified amount */
691
    public void stepUp(int n);
692
    
693
    /** Step down by specified amount */
694
    public void stepDown(int n);
695
}
696
```
697

698
### Form Interfaces
699

700
```java { .api }
701
/**
702
 * Interface for elements that can be submitted with forms
703
 */
704
public interface SubmittableElement {
705
    /** Get element name for form submission */
706
    String getName();
707
    
708
    /** Get element value for form submission */
709
    String getValue();
710
    
711
    /** Set default value */
712
    void setDefaultValue(String defaultValue);
713
    
714
    /** Reset to default value */
715
    void reset();
716
}
717

718
/**
719
 * Interface for elements that can be disabled
720
 */
721
public interface DisabledElement {
722
    /** Check if element is disabled */
723
    boolean isDisabled();
724
    
725
    /** Set disabled state */
726
    void setDisabled(boolean disabled);
727
}
728

729
/**
730
 * Interface for form validation
731
 */
732
public interface ValidatableElement {
733
    /** Check if element value is valid */
734
    boolean isValid();
735
    
736
    /** Get validation message */
737
    String getValidationMessage();
738
    
739
    /** Check validity and show message */
740
    boolean checkValidity();
741
    
742
    /** Set custom validation message */
743
    void setCustomValidity(String message);
744
}
745
```
746

747
### Form Encoding Types
748

749
```java { .api }
750
/**
751
 * Form encoding type constants
752
 */
753
public class FormEncodingType {
754
    /** URL encoded form data (default) */
755
    public static final FormEncodingType URL_ENCODED = new FormEncodingType("application/x-www-form-urlencoded");
756
    
757
    /** Multipart form data (for file uploads) */
758
    public static final FormEncodingType MULTIPART = new FormEncodingType("multipart/form-data");
759
    
760
    /** Plain text encoding */
761
    public static final FormEncodingType TEXT_PLAIN = new FormEncodingType("text/plain");
762
    
763
    /** Get encoding type name */
764
    public String getName();
765
}
766
```