Merge pull request #338 from MarketSquare/docs/post-multipart

Improved documentation for post multipart

Author: lucagiove

atests/test_post_multipart.robot

@@ -17,4 +17,6 @@ Test Post On Session Multipart
     ${resp}=    POST On Session  ${GLOBAL_SESSION}   /anything  files=${files}
 
     Should Contain  ${resp.json()}[headers][Content-Type]  multipart/form-data; boundary=
+    Should Contain  ${resp.json()}[headers][Content-Length]  480
     Should Contain  ${resp.json()}[files]  randombytes1
+    Should Contain  ${resp.json()}[files]  randombytes2

atests/testcase.robot

@@ -218,82 +218,33 @@ Post Request With File
 
 Post Request With Data and File
     [Tags]    post
-    Create Session    httpbin    http://httpbin.org
     &{data}=    Create Dictionary    name=mallikarjunarao    surname=kosuri
     Create File    foobar.txt    content=foobar
     ${file_data}=    Get File    foobar.txt
     &{files}=    Create Dictionary    file=${file_data}
-    ${resp}=    Post Request    httpbin    /post    files=${files}    data=${data}
+    ${resp}=    Post Request    ${test_session}    /anything    files=${files}    data=${data}
     Should Be Equal As Strings    ${resp.status_code}    200
 
 Put Requests
     [Tags]  put
-    Create Session  httpbin  http://httpbin.org
     &{data}=  Create Dictionary  name=bulkan  surname=evcimen
     &{headers}=  Create Dictionary  Content-Type=application/x-www-form-urlencoded
-    ${resp}=  Put Request  httpbin  /put  data=${data}  headers=${headers}
+    ${resp}=  Put Request  ${test_session}  /anything  data=${data}  headers=${headers}
     Dictionary Should Contain Value  ${resp.json()['form']}  bulkan
     Dictionary Should Contain Value  ${resp.json()['form']}  evcimen
 
-Head Request
-    [Tags]  head
-    Create Session  httpbin  http://httpbin.org
-    ${resp}=  Head Request  httpbin  /headers
-    Should Be Equal As Strings  ${resp.status_code}  200
-
-Options Request
-    [Tags]  options
-    Create Session  httpbin  http://httpbin.org
-    ${resp}=  Options Request  httpbin  /headers
-    Should Be Equal As Strings  ${resp.status_code}  200
-    Dictionary Should Contain Key  ${resp.headers}  allow
-
-Delete Request With URL Params
-    [Tags]  delete
-    Create Session  httpbin  http://httpbin.org
-    &{params}=   Create Dictionary   key=value     key2=value2
-    ${resp}=  Delete Request  httpbin  /delete		${params}
-    Should Be Equal As Strings  ${resp.status_code}  200
-
-Delete Request With No Data
-    [Tags]  delete
-    Create Session  httpbin  http://httpbin.org
-    ${resp}=  Delete Request  httpbin  /delete
-    Should Be Equal As Strings  ${resp.status_code}  200
-
-Delete Request With Data
-    [Tags]  delete
-    Create Session  httpbin  http://httpbin.org    debug=3
-    &{data}=  Create Dictionary  name=bulkan  surname=evcimen
-    ${resp}=  Delete Request  httpbin  /delete  data=${data}
-    Should Be Equal As Strings  ${resp.status_code}  200
-    Log  ${resp.content}
-    Comment  Dictionary Should Contain Value  ${resp.json()['data']}  bulkan
-    Comment  Dictionary Should Contain Value  ${resp.json()['data']}  evcimen
-
-Delete Requests with Json Data
-    [Tags]  delete
-    Create Session  httpbin     http://httpbin.org
-    &{data}=    Create Dictionary   latitude=30.496346  longitude=-87.640356
-    ${resp}=     Delete Request  httpbin  /delete    json=${data}
-    Should Be Equal As Strings  ${resp.status_code}  200
-    ${jsondata}=  Set Variable  ${resp.json()}
-    Should Be Equal     ${jsondata['json']}     ${data}
-
 Patch Requests
     [Tags]    patch
-    Create Session    httpbin    http://httpbin.org
     &{data}=    Create Dictionary    name=bulkan    surname=evcimen
     &{headers}=    Create Dictionary    Content-Type=application/x-www-form-urlencoded
-    ${resp}=    Patch Request    httpbin    /patch    data=${data}    headers=${headers}
+    ${resp}=    Patch Request    ${test_session}    /anything    data=${data}    headers=${headers}
     Dictionary Should Contain Value    ${resp.json()['form']}    bulkan
     Dictionary Should Contain Value    ${resp.json()['form']}    evcimen
 
 Patch Requests with Json Data
     [Tags]  patch
-    Create Session  httpbin     http://httpbin.org
     &{data}=    Create Dictionary   latitude=30.496346  longitude=-87.640356
-    ${resp}=     Patch Request  httpbin  /patch    json=${data}
+    ${resp}=     Patch Request  ${test_session}  /anything    json=${data}
     Should Be Equal As Strings  ${resp.status_code}  200
     ${jsondata}=  Set Variable  ${resp.json()}
     Should Be Equal     ${jsondata['json']}     ${data}

doc/RequestsLibrary.html

@@ -94,6 +94,30 @@ class RequestsLibrary(RequestsOnSessionKeywords, DeprecatedKeywords):
         | status_code | Integer Code of responded HTTP Status, e.g. 404 or 200. |
         | text    | Content of the response, in unicode. If ``response.encoding`` is ``None``, encoding will be guessed using chardet. The encoding of the response content is determined based solely on HTTP headers, following RFC 2616 to the letter. If you can take advantage of non-HTTP knowledge to make a better guess at the encoding, you should set ``response.encoding`` appropriately before accessing this property. |
         | url     | Final URL location of Response. |
+
+        = POST a Multipart-Encoded File =
+
+        RequestsLibrary makes it simple to upload Multipart-encoded files, but in order to make sure that the
+        Python Library provides automatically the right ``Content-Length`` and ``multipart/form-data; boundary=...``
+        headers you SHOULD NOT provide those headers manually, use the keyword
+        `Get File For Streaming Upload` instead that opens the files in binary mode.
+
+        Below an example of multiple file sent over a single POST:
+
+        |   Test Post Multiple Files
+        |       ${file_1}=  Get File For Streaming Upload  files/randombytes.bin
+        |       ${file_2}=  Get File For Streaming Upload  files/randombytes.bin
+        |       ${files}=   Create Dictionary  randombytes1  ${file_1}  randombytes2  ${file_2}
+        |
+        |       ${resp}=    POST  https://someurl  files=${files}
+
+        You can find a working test example in `atests/test_post_multipart.robot`.
+
+        For a complete reference verify the official Requests documentation:
+
+          - https://2.python-requests.org/en/master/user/quickstart/#post-a-multipart-encoded-file
+          - https://2.python-requests.org/en/master/user/advanced/#post-multiple-multipart-encoded-files
+
         """
     __version__ = VERSION
     ROBOT_LIBRARY_SCOPE = 'GLOBAL'