PhoenixIntegration.Requests.follow_form

You're seeing just the function follow_form, go back to PhoenixIntegration.Requests module for more information.
Link to this function

follow_form(conn, fields, opts \\ %{})

View Source

Finds a form in conn.resp_body, fills out the fields with the given data, requests the form's action, follows any redirects and returns the resulting conn.

Similar to submit_form, except that it does follow redirects.

Parameters

  • conn should be a conn returned from a previous request that rendered some html. The functions are designed to pass the conn from one call into the next via pipes.
  • fields is a map of fields and data to be written into the form before submitting its action. The data can take one of three forms:
    • Most frequently, it's a string.
    • It can be a list of strings. That's used when a set of tags in the form have names ending with [] to tell Phoenix to create a list value. See the example below.
    • It can be an Elixir struct like DateTime. In that case, the fields within the struct are used to find matching tags (by name) in the form. Fields that don't match are ignored. See the example below.
    • If you use Plug.Upload, you can set an input type="file" value to the %Plug.Upload{} value you'd expect Phoenix to deliver to your controller action. See the example below.
  • opts A map of additional options
    • identifier indicates which link to find in the html. Defaults to nil. Valid values can be in the following forms:
      • "/some/path" specify the link's href starting with a "/" character
      • "http://www.example.com/some/uri", specify the href as full uri starting with either "http" or "https"
      • "#element-id" specify the html element id of the link you are looking for. Must start start with the "#" character (same as css id specifier).
      • "Some Text" specify text contained within the link you are looking for.
    • :method - restricts the forms searched to those whose action uses the given method (such as "post" or "put"). Defaults to nil;
    • :finder - finding string passed to Floki.find. Defaults to "form"

If no opts.identifier is specified, the first form that makes sense is used. Unless you have multiple forms on your page, this often is the most understandable pattern.

If no appropriate form is found, follow_form raises an error.

Example:

  upload = %Plug.Upload{
    content_type: "image/jpg",
    path: "/var/mytests/photo.jpg",
    filename: "photo.jpg"}

  # fill out a form and submit it
  get( conn, thing_path(conn, :edit, thing) )
  |> follow_form( %{ thing: %{
      name: "Updated Name",
      expires: ~D[2011-09-23],
      some_count: 42,
      comments: ["first", "second"],
      photo: upload
    }})
  |> assert_response( status: 200, path: thing_path(conn, :show, thing) )

In this example, the form would contain list-creating HTML like this:

 <input id="comment1" type="text" name="thing[comments][]" value="">
 <input id="comment2" type="text" name="thing[comments][]" value="">

As it happens, the form has tags for only the month and year of the expiration date:

 <select name="thing[expires][year]"> ... </select>
 <select name="thing[expires][month]"> ... </select>

... so the day part of the Date is ignored.

The photo part of the form might have been created like this:

 <%= file_input f, :photo %>