Ease Testing Forms w/`LocalForm`

[SergioBenitez]

Testing forms in Rocket is currently an entirely manual process:

let client = Client::tracked(rocket).unwrap();

let response = client.post("/")
    .header(ContentType::Form)
    .body("field=value&is+it=a+cat%3F")
    .dispatch();

With the addition of multipart form support, form testing verbosity is even further exacerbated:

let client = Client::tracked(rocket).unwrap();

let ct = "multipart/form-data; boundary=X-BOUNDARY"
    .parse::<ContentType>()
    .unwrap();

let body = &[
    "--X-BOUNDARY",
    r#"Content-Disposition: form-data; name="names[]""#,
    "",
    "abcd",
    "--X-BOUNDARY",
    r#"Content-Disposition: form-data; name="names[]""#,
    "",
    "123",
    "--X-BOUNDARY",
    r#"Content-Disposition: form-data; name="file"; filename="foo.txt""#,
    "Content-Type: text/plain",
    "",
    "hi there",
    "--X-BOUNDARY--",
    "",
].join("\r\n");

let response = client.post("/")
    .header(ct)
    .body(body)
    .dispatch();

Rocket should make testing applications with forms a much simpler task.

Here's how we might hope testing the above forms would look:

let client = Client::tracked(rocket).unwrap();
let response = client.post("/")
    .form(&[("field", "value"), ("is it", "a cat?")])
    .dispatch();

let client = Client::tracked(rocket).unwrap();
let response = client.post("/")
    .form(LocalForm::new()
        .field("names[]", "abcd")
        .field("names[]", "123")
        .file("foo.txt", ContentType::Plain, "hi there"))
    .dispatch();

An API enabling this might resemble:

impl Client {
    pub fn form<F: Into<LocalForm>>(&mut self, form: F) -> &mut Self {
        let form = form.into();
        self.set_header(form.content_type());
        self.set_body(form.body_data());
        self
    }
}

struct LocalForm { /* .. */ }

impl LocalForm {
    pub fn new() -> Self;

    /// A percent-decoded `name` and `value`.
    pub fn field<'v, N, V>(mut self, name: N, value: V) -> Self
        where N: Into<NameBuf<'v>>, V: AsRef<str>;

    /// Adds all of the `fields` to `self`.
    pub fn fields<'v, I, F>(mut self, fields: I) -> Self
        where I: Iterator<Item = F>, F: Into<ValueField<'v>>;

    /// A percent-encoded `name` and `value`.
    pub fn raw_field(mut self, name: &'v RawStr, value: &'v RawStr) -> Self;

    /// Adds a field for the file with name `file_name`, content-type `ct`, and
    /// file contents `data`.
    pub fn file<'v, N, V>(mut self, file_name: N, ct: ContentType, data: V) -> Self
        where N: Into<Option<&'v str>>, V: AsRef<[u8]>;

    /// Add a data field with content-type `ct` and binary `data`.
    pub fn data<'v, V>(mut self, ct: ContentType, data: V) -> Self
        where V: AsRef<[u8]>;

    /// The full content-type for this form.
    pub fn content_type(&self) -> ContentType;

    /// The full body data for this form.
    pub fn body_data(&self) -> Vec<u8>;
}

impl<'v, F: Into<ValueField<'v>>, I: Iterator<Item = F>> From<I> for LocalForm { /* .. */ }

[ELD]

I'll go ahead and take this one on if no one else is 🙂

[SergioBenitez]

It's yours!

[sabirmgd]

By referring to #1591 (comment), would there be an implementation to upload local files?

I was experimenting with the example posted to do that but no luck:

let ct = "multipart/form-data; boundary=X-BOUNDARY"
        .parse::<ContentType>()
        .unwrap();

    let body = &[
        "--X-BOUNDARY",
        r#"Content-Disposition: form-data; name="data"; filename="@./files/24.dcm""#,
        "",
        "--X-BOUNDARY--",
        "",
    ]
    .join("\r\n");

my end point receives a field called data and it works when I test it with postman.

[jebrosen]

and it works when I test it with postman.

As far as I know the @filename syntax is a feature of curl, and it's used to distinguish a file field from a non-file field. I don't see this feature documented on Postman's website; does it get that by using curl as a backend?

This syntax doesn't seem nearly as useful in Rust code as it is on the command-line, since tests already have convenient filesystem access and field vs file would already be distinguished:

let client = Client::tracked(rocket).unwrap();
let response = client.post("/")
    .form(LocalForm::new()
        .field("names[]", "abcd")
        .field("names[]", "123")
        .file("foo.txt", ContentType::Plain, std::fs::read("test_data/foo.txt")))
    .dispatch();

But I could imagine an API like this, which might be useful for upload-heavy tests:

let client = Client::tracked(rocket).unwrap();
let response = client.post("/")
    .form(LocalForm::new()
        .field("names[]", "abcd")
        .field("names[]", "123")
        .file_on_disk("foo.txt") // Content-Type inferred from extension similarly to NamedFile
    .dispatch();

[sabirmgd]

does it get that by using curl as a backend?

I'm not sure how it really works in postman, but they would be handling IO separately, a quick google search revealed that postman is written in JS. I use another tool (Insomnia) that generate code and just for reference here is the generated curl code:

curl --request POST \
  --url http://localhost:3000/api/studies \
  --header 'Content-Type: multipart/form-data; boundary=---011000010111000001101001' \
  --form 'data=@C:\Path\To\MyFile' \
  --form =

and here is the generated code for python:

import http.client

conn = http.client.HTTPConnection("localhost:3000")

payload = "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"data\"; filename=\"Weld 5 mmDemo ImagesUli.DCM\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"\"\r\n\r\n\r\n-----011000010111000001101001--\r\n"

headers = { 'Content-Type': "multipart/form-data; boundary=---011000010111000001101001" }

conn.request("POST", "/api/studies", payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

They don't seem to handle IO by themselves, could it be pure http? The http generated code is:

POST /api/studies HTTP/1.1
Content-Type: multipart/form-data; boundary=---011000010111000001101001
Host: localhost:3000
Content-Length: 229

-----011000010111000001101001
Content-Disposition: form-data; name="data"; filename="Weld 5 mmDemo ImagesUli.DCM"


-----011000010111000001101001
Content-Disposition: form-data; name=""


-----011000010111000001101001--

[jebrosen]

They don't seem to handle IO by themselves, could it be pure http? The http generated code is:

No; HTTP itself knows nothing about the semantics of the payload data, especially not for something as complicated to parse as multipart/form-data. The command generated for curl takes advantage of the @ feature of --form, but the generated code for both the python and raw HTTP represent an upload of an empty file.