Submits the given form on the page, optionally with the given form
values. Pass the form field's values as an array in the second
parameter.
Although this function can be used as a short-hand version of
fillField(), selectOption(), click() etc. it has some important
differences:
* Only field *names* may be used, not CSS/XPath selectors nor field labels
* If a field is sent to this function that does *not* exist on the page,
it will silently be added to the HTTP request. This is helpful for testing
some types of forms, but be aware that you will *not* get an exception
like you would if you called fillField() or selectOption() with
a missing field.
Fields that are not provided will be filled by their values from the page,
or from any previous calls to fillField(), selectOption() etc.
You don't need to click the 'Submit' button afterwards.
This command itself triggers the request to form's action.
You can optionally specify which button's value to include
in the request with the last parameter (as an alternative to
explicitly setting its value in the second parameter), as
button values are not otherwise included in the request.
Examples:
php
submitForm('#login', [
'login' => 'davert',
'password' => '123456'
]);
or
$I->submitForm('#login', [
'login' => 'davert',
'password' => '123456'
], 'submitButtonName');
For example, given this sample "Sign Up" form:
html
You could write the following to submit it:
php
submitForm(
'#userForm',
[
'user' => [
'login' => 'Davert',
'password' => '123456',
'agree' => true
]
],
'submitButton'
);
Note that "2" will be the submitted value for the "plan" field, as it is
the selected option.
You can also emulate a JavaScript submission by not specifying any
buttons in the third parameter to submitForm.
php
submitForm(
'#userForm',
[
'user' => [
'login' => 'Davert',
'password' => '123456',
'agree' => true
]
]
);
This function works well when paired with seeInFormFields()
for quickly testing CRUD interfaces and form validation logic.
php
'value',
'field2' => 'another value',
'checkbox1' => true,
...
];
$I->submitForm('#my-form', $form, 'submitButton');
$I->amOnPage('/path/to/form-page') may be needed
$I->seeInFormFields('#my-form', $form);
Parameter values can be set to arrays for multiple input fields
of the same name, or multi-select combo boxes. For checkboxes,
you can use either the string value or boolean true/false which will
be replaced by the checkbox's value in the DOM.
php
submitForm('#my-form', [
'field1' => 'value',
'checkbox' => [
'value of first checkbox',
'value of second checkbox',
],
'otherCheckboxes' => [
true,
false,
false
],
'multiselect' => [
'first option value',
'second option value'
]
]);
Mixing string and boolean values for a checkbox's value is not supported
and may produce unexpected results.
Field names ending in [] must be passed without the trailing square
bracket characters, and must contain an array for its value. This allows
submitting multiple values with the same name, consider:
php
submitForm('#my-form', [
'field[]' => 'value',
'field[]' => 'another value', // 'field[]' is already a defined key
]);
The solution is to pass an array value:
php
submitForm('#my-form', [
'field' => [
'value',
'another value',
]
]);