| Library version: | 0.9 |
|---|---|
| Library scope: | GLOBAL |
| Named arguments: | not supported |
RequestsLibrary is a Robot Framework library aimed to provide HTTP api testing functionalities by wrapping the well known Python Requests Library.
The quickest way to start is using the requests keywords and urls see below examples:
* Settings *
Library RequestsLibrary
* Test Cases *
Quick Get Request
${response}= GET https://www.google.com
Quick Get Request With Parameters Test
${response}= GET https://www.google.com/search params=query=ciao expected_status=200
Quick Get A JSON Body
${response}= GET https://jsonplaceholder.typicode.com/posts/1
Should Be Equal As Strings 1 ${response.json()}[id]
In order to share the HTTP Session (with the same url, headers, cookies, etc.) among multiple requests, a new connection needs to be prepared with Create Session and passed to the * On Session keywords. You can then execute any * On Session keywords on the shared session by passing the created session alias name, this will increase performances since the connection and ssl handshake is recycled and not repeated for each requests. Below some more advanced examples:
* Settings * Library Collections Library RequestsLibrary Suite Setup Create Session jsonplaceholder https://jsonplaceholder.typicode.com * Test Cases * Get Request Test Create Session google http://www.google.com ${resp_google}= GET On Session google / expected_status=200 ${resp_json}= GET On Session jsonplaceholder /posts/1 Should Be Equal As Strings ${resp_google.reason} OK Dictionary Should Contain Value ${resp_json.json()} sunt aut facere repellat provident Post Request Test &{data}= Create dictionary title=Robotframework requests body=This is a test! userId=1 ${resp}= POST On Session jsonplaceholder /posts json=${data} expected_status=anything Status Should Be 201 ${resp} Dictionary Should Contain Key ${resp.json()} id
All the HTTP requests keywords (GET, POST, PUT, etc.) return an extremely useful Response object. The Response object contains a server's response to an HTTP request.
You can access the different attributes with the dot notation in this way: ${response.json()} or ${response.text}. Below the list of the most useful attributes:
| Attributes | Explanation |
|---|---|
| content | Content of the response, in bytes. |
| cookies | A CookieJar of Cookies the server sent back. |
| elapsed | The amount of time elapsed between sending the request and the arrival of the response (as a timedelta). This property specifically measures the time taken between sending the first byte of the request and finishing parsing the headers. It is therefore unaffected by consuming the response content or the value of the stream keyword argument. |
| encoding | Encoding to decode with when accessing response.text. |
| headers | Case-insensitive Dictionary of Response Headers. For example, headers['content-encoding'] will return the value of a `Content-Encoding' response header. |
| history | A list of Response objects from the history of the Request. Any redirect responses will end up here. The list is sorted from the oldest to the most recent request. |
| json | Returns the json-encoded content of a response, if any. Parameters: **kwargs - Optional arguments that json.loads takes. Raises: ValueError ? If the response body does not contain valid json. |
| ok | Returns True if status_code is less than 400, False if not. |
| reason | Textual reason of responded HTTP Status, e.g. Not Found or OK. |
| 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. |
Create Session: create a HTTP session to a server
url Base url of the server
alias Robot Framework alias to identify the session
headers Dictionary of default headers
cookies Dictionary of cookies
client_certs ['client certificate', 'client key'] PEM files containing the client key and certificate
timeout Connection timeout
proxies Dictionary that contains proxy urls for HTTP and HTTPS communication
verify Whether the SSL cert will be verified. A CA_BUNDLE path can also be provided. Defaults to False.
debug Enable http verbosity option more information https://docs.python.org/2/library/httplib.html#httplib.HTTPConnection.set_debuglevel
max_retries Number of maximum retries each connection should attempt. By default it will retry 3 times in case of connection errors only. A 0 value will disable any kind of retries regardless of other retry settings. In case the number of retries is reached a retry exception is raised.
disable_warnings Disable requests warning useful when you have large number of testcases
backoff_factor Introduces a delay time between retries that is longer after each retry. eg. if backoff_factor is set to 0.1 the sleep between attemps will be: 0.0, 0.2, 0.4 More info here: https://urllib3.readthedocs.io/en/latest/reference/urllib3.util.html
retry_method_list List of uppercased HTTP method verbs where retries are allowed. By default retries are allowed only on HTTP requests methods that are considered to be idempotent (multiple requests with the same parameters end with the same state). eg. set to ['POST', 'GET'] to retry only those kind of requests.
retry_status_list List of integer HTTP status codes that, if returned, a retry is attempted. eg. set to [502, 503] to retry requests if those status are returned. Note that max_retries must be greater than 0.
Create Session: create a HTTP session to a server
url Base url of the server
alias Robot Framework alias to identify the session
headers Dictionary of default headers
cookies Dictionary of cookies
auth A Custom Authentication object to be passed on to the requests library. http://docs.python-requests.org/en/master/user/advanced/#custom-authentication
timeout Connection timeout
proxies Dictionary that contains proxy urls for HTTP and HTTPS communication
verify Whether the SSL cert will be verified. A CA_BUNDLE path can also be provided. Defaults to False.
debug Enable http verbosity option more information https://docs.python.org/2/library/httplib.html#httplib.HTTPConnection.set_debuglevel
max_retries Number of maximum retries each connection should attempt. By default it will retry 3 times in case of connection errors only. A 0 value will disable any kind of retries regardless of other retry settings. In case the number of retries is reached a retry exception is raised.
disable_warnings Disable requests warning useful when you have large number of testcases
backoff_factor Introduces a delay time between retries that is longer after each retry. eg. if backoff_factor is set to 0.1 the sleep between attemps will be: 0.0, 0.2, 0.4 More info here: https://urllib3.readthedocs.io/en/latest/reference/urllib3.util.html
retry_method_list List of uppercased HTTP method verbs where retries are allowed. By default retries are allowed only on HTTP requests methods that are considered to be idempotent (multiple requests with the same parameters end with the same state). eg. set to ['POST', 'GET'] to retry only those kind of requests.
retry_status_list List of integer HTTP status codes that, if returned, a retry is attempted. eg. set to [502, 503] to retry requests if those status are returned. Note that max_retries must be greater than 0.
Create Session: create a HTTP session to a server
url Base url of the server
alias Robot Framework alias to identify the session
headers Dictionary of default headers
cookies Dictionary of cookies
auth ['DOMAIN', 'username', 'password'] for NTLM Authentication
timeout Connection timeout
proxies Dictionary that contains proxy urls for HTTP and HTTPS communication
verify Whether the SSL cert will be verified. A CA_BUNDLE path can also be provided. Defaults to False.
debug Enable http verbosity option more information https://docs.python.org/2/library/httplib.html#httplib.HTTPConnection.set_debuglevel
max_retries Number of maximum retries each connection should attempt. By default it will retry 3 times in case of connection errors only. A 0 value will disable any kind of retries regardless of other retry settings. In case the number of retries is reached a retry exception is raised.
disable_warnings Disable requests warning useful when you have large number of testcases
backoff_factor Introduces a delay time between retries that is longer after each retry. eg. if backoff_factor is set to 0.1 the sleep between attemps will be: 0.0, 0.2, 0.4 More info here: https://urllib3.readthedocs.io/en/latest/reference/urllib3.util.html
retry_method_list List of uppercased HTTP method verbs where retries are allowed. By default retries are allowed only on HTTP requests methods that are considered to be idempotent (multiple requests with the same parameters end with the same state). eg. set to ['POST', 'GET'] to retry only those kind of requests.
retry_status_list List of integer HTTP status codes that, if returned, a retry is attempted. eg. set to [502, 503] to retry requests if those status are returned. Note that max_retries must be greater than 0.
Create Session: create a HTTP session to a server
url Base url of the server
alias Robot Framework alias to identify the session
headers Dictionary of default headers
cookies Dictionary of cookies
auth ['DOMAIN', 'username', 'password'] for NTLM Authentication
timeout Connection timeout
proxies Dictionary that contains proxy urls for HTTP and HTTPS communication
verify Whether the SSL cert will be verified. A CA_BUNDLE path can also be provided. Defaults to False.
debug Enable http verbosity option more information https://docs.python.org/2/library/httplib.html#httplib.HTTPConnection.set_debuglevel
max_retries Number of maximum retries each connection should attempt. By default it will retry 3 times in case of connection errors only. A 0 value will disable any kind of retries regardless of other retry settings. In case the number of retries is reached a retry exception is raised.
disable_warnings Disable requests warning useful when you have large number of testcases
backoff_factor Introduces a delay time between retries that is longer after each retry. eg. if backoff_factor is set to 0.1 the sleep between attemps will be: 0.0, 0.2, 0.4 More info here: https://urllib3.readthedocs.io/en/latest/reference/urllib3.util.html
retry_method_list List of uppercased HTTP method verbs where retries are allowed. By default retries are allowed only on HTTP requests methods that are considered to be idempotent (multiple requests with the same parameters end with the same state). eg. set to ['POST', 'GET'] to retry only those kind of requests.
retry_status_list List of integer HTTP status codes that, if returned, a retry is attempted. eg. set to [502, 503] to retry requests if those status are returned. Note that max_retries must be greater than 0.
Create Session: create a HTTP session to a server
alias Robot Framework alias to identify the session
url Base url of the server
headers Dictionary of default headers
cookies Dictionary of cookies
auth List of username & password for HTTP Basic Auth
timeout Connection timeout
proxies Dictionary that contains proxy urls for HTTP and HTTPS communication
verify Whether the SSL cert will be verified. A CA_BUNDLE path can also be provided.
debug Enable http verbosity option more information https://docs.python.org/2/library/httplib.html#httplib.HTTPConnection.set_debuglevel
max_retries Number of maximum retries each connection should attempt. By default it will retry 3 times in case of connection errors only. A 0 value will disable any kind of retries regardless of other retry settings. In case the number of retries is reached a retry exception is raised.
disable_warnings Disable requests warning useful when you have large number of testcases
backoff_factor Introduces a delay time between retries that is longer after each retry. eg. if backoff_factor is set to 0.1 the sleep between attemps will be: 0.0, 0.2, 0.4 More info here: https://urllib3.readthedocs.io/en/latest/reference/urllib3.util.html
retry_method_list List of uppercased HTTP method verbs where retries are allowed. By default retries are allowed only on HTTP requests methods that are considered to be idempotent (multiple requests with the same parameters end with the same state). eg. set to ['POST', 'GET'] to retry only those kind of requests.
retry_status_list List of integer HTTP status codes that, if returned, a retry is attempted. eg. set to [502, 503] to retry requests if those status are returned. Note that max_retries must be greater than 0.
Sends a DELETE request.
The endpoint used to send the request is the url parameter.
By default this keyword fails if a status code with error values is returned in the response, this behavior can be modified using the expected_status and msg parameters, read more about it in Status Should Be keyword documentation. In order to disable this implicit assert mechanism you can pass as expected_status the values any or anything.
Other optional requests arguments can be passed using **kwargs see the GET keyword for the complete list.
Removes all the session objects
Sends a DELETE request on a previously created HTTP Session.
Session will be identified using the alias name. The endpoint used to send the request is the url parameter.
By default this keyword fails if a status code with error values is returned in the response, this behavior can be modified using the expected_status and msg parameters, read more about it in Status Should Be keyword documentation. In order to disable this implicit assert mechanism you can pass as expected_status the values any or anything.
Other optional requests arguments can be passed using **kwargs see the GET keyword for the complete list.
DEPRECATED Please use DELETE On Session instead.
Send a DELETE request on the session object found using the given alias
alias that will be used to identify the Session object in the cache
uri to send the DELETE request to
json a value that will be json encoded and sent as request data if data is not specified
headers a dictionary of headers to use with the request
allow_redirects Boolean. Set to True if POST/PUT/DELETE redirect following is allowed.
timeout connection timeout
Sends a GET request.
The endpoint used to retrieve the resource is the url, while query string parameters can be passed as string, dictionary (or list of tuples or bytes) through the params.
By default this keyword fails if a status code with error values is returned in the response, this behavior can be modified using the expected_status and msg parameters, read more about it in Status Should Be keyword documentation. In order to disable this implicit assert mechanism you can pass as expected_status the values any or anything.
Other optional requests arguments can be passed using **kwargs here is a list:
data |
Dictionary, list of tuples, bytes, or file-like object to send in the body of the request. |
json |
A JSON serializable Python object to send in the body of the request. |
headers |
Dictionary of HTTP Headers to send with the request. |
cookies |
Dict or CookieJar object to send with the request. |
files |
Dictionary of file-like-objects (or {'name': file-tuple}) for multipart encoding upload. |
file-tuple |
can be a 2-tuple ('filename', fileobj), 3-tuple ('filename', fileobj, 'content_type') or a 4-tuple ('filename', fileobj, 'content_type', custom_headers), where 'content-type' is a string defining the content type of the given file and custom_headers a dict-like object containing additional headers to add for the file. |
auth |
Auth tuple to enable Basic/Digest/Custom HTTP Auth. |
timeout |
How many seconds to wait for the server to send data before giving up, as a float, or a (connect timeout, read timeout) tuple. |
allow_redirects |
Boolean. Enable/disable GET/OPTIONS/POST/PUT/PATCH/DELETE/HEAD redirection. Defaults to True. |
proxies |
Dictionary mapping protocol to the URL of the proxy. |
verify |
Either a boolean, in which case it controls whether we verify the server's TLS certificate, or a string, in which case it must be a path to a CA bundle to use. Defaults to True. Warning: if a session has been created with verify=False any other requests will not verify the SSL certificate. |
stream |
if False, the response content will be immediately downloaded. |
cert |
if String, path to ssl client cert file (.pem). If Tuple, ('cert', 'key') pair. |
For more updated and complete information verify the official Requests api documentation: https://requests.readthedocs.io/en/latest/api/
Opens and returns a file descriptor of a specified file to be passed as data parameter to other requests keywords.
This allows streaming upload of large files without reading them into memory.
File descriptor is binary mode and read only. Requests keywords will automatically close the file, if used outside this library it's up to the caller to close it.
Sends a GET request on a previously created HTTP Session.
Session will be identified using the alias name. The endpoint used to retrieve the resource is the url, while query string parameters can be passed as string, dictionary (or list of tuples or bytes) through the params.
By default this keyword fails if a status code with error values is returned in the response, this behavior can be modified using the expected_status and msg parameters, read more about it in Status Should Be keyword documentation. In order to disable this implicit assert mechanism you can pass as expected_status the values any or anything.
Other optional requests arguments can be passed using **kwargs see the GET keyword for the complete list.
DEPRECATED Please use GET On Session instead.
Send a GET request on the session object found using the given alias
alias that will be used to identify the Session object in the cache
uri to send the GET request to
params url parameters to append to the uri
headers a dictionary of headers to use with the request
data a dictionary of key-value pairs that will be urlencoded and sent as GET data or binary data that is sent as the raw body content
json a value that will be json encoded and sent as GET data if data is not specified
allow_redirects Boolean. Set to True if POST/PUT/DELETE redirect following is allowed.
timeout connection timeout
Sends a HEAD request.
The endpoint used to retrieve the HTTP headers is the url.
allow_redirects parameter is not provided, it will be set to False (as opposed to the default behavior).
By default this keyword fails if a status code with error values is returned in the response, this behavior can be modified using the expected_status and msg parameters, read more about it in Status Should Be keyword documentation. In order to disable this implicit assert mechanism you can pass as expected_status the values any or anything.
Other optional requests arguments can be passed using **kwargs see the GET keyword for the complete list.
Sends a HEAD request on a previously created HTTP Session.
Session will be identified using the alias name. The endpoint used to retrieve the HTTP headers is the url.
allow_redirects parameter is not provided, it will be set to False (as opposed to the default behavior).
By default this keyword fails if a status code with error values is returned in the response, this behavior can be modified using the expected_status and msg parameters, read more about it in Status Should Be keyword documentation. In order to disable this implicit assert mechanism you can pass as expected_status the values any or anything.
Other optional requests arguments can be passed using **kwargs see the GET keyword for the complete list.
DEPRECATED Please use HEAD On Session instead.
Send a HEAD request on the session object found using the given alias
alias that will be used to identify the Session object in the cache
uri to send the HEAD request to
allow_redirects Boolean. Set to True if POST/PUT/DELETE redirect following is allowed.
headers a dictionary of headers to use with the request
timeout connection timeout
Sends a OPTIONS request.
The endpoint used to retrieve the resource is the url.
By default this keyword fails if a status code with error values is returned in the response, this behavior can be modified using the expected_status and msg parameters, read more about it in Status Should Be keyword documentation. In order to disable this implicit assert mechanism you can pass as expected_status the values any or anything.
Other optional requests arguments can be passed using **kwargs see the GET keyword for the complete list.
Sends a OPTIONS request on a previously created HTTP Session.
Session will be identified using the alias name. The endpoint used to retrieve the resource is the url.
By default this keyword fails if a status code with error values is returned in the response, this behavior can be modified using the expected_status and msg parameters, read more about it in Status Should Be keyword documentation. In order to disable this implicit assert mechanism you can pass as expected_status the values any or anything.
Other optional requests arguments can be passed using **kwargs see the GET keyword for the complete list.
DEPRECATED Please use OPTIONS On Session instead.
Send an OPTIONS request on the session object found using the given alias
alias that will be used to identify the Session object in the cache
uri to send the OPTIONS request to
allow_redirects Boolean. Set to True if POST/PUT/DELETE redirect following is allowed.
headers a dictionary of headers to use with the request
timeout connection timeout
Sends a PUT request.
The endpoint used to send the request is the url parameter, while its body can be passed using data or json parameters.
data can be a dictionary, list of tuples, bytes, or file-like object. If you want to pass a json body pass a dictionary as json parameter.
By default this keyword fails if a status code with error values is returned in the response, this behavior can be modified using the expected_status and msg parameters, read more about it in Status Should Be keyword documentation. In order to disable this implicit assert mechanism you can pass as expected_status the values any or anything.
Other optional requests arguments can be passed using **kwargs see the GET keyword for the complete list.
Sends a PATCH request on a previously created HTTP Session.
Session will be identified using the alias name. The endpoint used to send the request is the url parameter, while its body can be passed using data or json parameters.
data can be a dictionary, list of tuples, bytes, or file-like object. If you want to pass a json body pass a dictionary as json parameter.
By default this keyword fails if a status code with error values is returned in the response, this behavior can be modified using the expected_status and msg parameters, read more about it in Status Should Be keyword documentation. In order to disable this implicit assert mechanism you can pass as expected_status the values any or anything.
Other optional requests arguments can be passed using **kwargs see the GET keyword for the complete list.
DEPRECATED Please use PATCH On Session instead.
Send a PATCH request on the session object found using the given alias
alias that will be used to identify the Session object in the cache
uri to send the PATCH request to
data a dictionary of key-value pairs that will be urlencoded and sent as PATCH data or binary data that is sent as the raw body content or file descriptor retrieved by Get File For Streaming Upload
json a value that will be json encoded and sent as PATCH data if data is not specified
headers a dictionary of headers to use with the request
files a dictionary of file names containing file data to PATCH to the server
allow_redirects Boolean. Set to True if POST/PUT/DELETE redirect following is allowed.
params url parameters to append to the uri
timeout connection timeout
Sends a POST request.
The endpoint used to send the request is the url parameter, while its body can be passed using data or json parameters.
data can be a dictionary, list of tuples, bytes, or file-like object. If you want to pass a json body pass a dictionary as json parameter.
By default this keyword fails if a status code with error values is returned in the response, this behavior can be modified using the expected_status and msg parameters, read more about it in Status Should Be keyword documentation. In order to disable this implicit assert mechanism you can pass as expected_status the values any or anything.
Other optional requests arguments can be passed using **kwargs see the GET keyword for the complete list.
Sends a POST request on a previously created HTTP Session.
Session will be identified using the alias name. The endpoint used to send the request is the url parameter, while its body can be passed using data or json parameters.
data can be a dictionary, list of tuples, bytes, or file-like object. If you want to pass a json body pass a dictionary as json parameter.
By default this keyword fails if a status code with error values is returned in the response, this behavior can be modified using the expected_status and msg parameters, read more about it in Status Should Be keyword documentation. In order to disable this implicit assert mechanism you can pass as expected_status the values any or anything.
Other optional requests arguments can be passed using **kwargs see the GET keyword for the complete list.
DEPRECATED Please use POST On Session instead.
Send a POST request on the session object found using the given alias
alias that will be used to identify the Session object in the cache
uri to send the POST request to
data a dictionary of key-value pairs that will be urlencoded and sent as POST data or binary data that is sent as the raw body content or passed as such for multipart form data if files is also defined or file descriptor retrieved by Get File For Streaming Upload
json a value that will be json encoded and sent as POST data if files or data is not specified
params url parameters to append to the uri
headers a dictionary of headers to use with the request
files a dictionary of file names containing file data to POST to the server
allow_redirects Boolean. Set to True if POST/PUT/DELETE redirect following is allowed.
timeout connection timeout
Sends a PUT request.
The endpoint used to send the request is the url parameter, while its body can be passed using data or json parameters.
data can be a dictionary, list of tuples, bytes, or file-like object. If you want to pass a json body pass a dictionary as json parameter.
By default this keyword fails if a status code with error values is returned in the response, this behavior can be modified using the expected_status and msg parameters, read more about it in Status Should Be keyword documentation. In order to disable this implicit assert mechanism you can pass as expected_status the values any or anything.
Other optional requests arguments can be passed using **kwargs see the GET keyword for the complete list.
Sends a PUT request on a previously created HTTP Session.
Session will be identified using the alias name. The endpoint used to send the request is the url parameter, while its body can be passed using data or json parameters.
data can be a dictionary, list of tuples, bytes, or file-like object. If you want to pass a json body pass a dictionary as json parameter.
By default this keyword fails if a status code with error values is returned in the response, this behavior can be modified using the expected_status and msg parameters, read more about it in Status Should Be keyword documentation. In order to disable this implicit assert mechanism you can pass as expected_status the values any or anything.
Other optional requests arguments can be passed using **kwargs see the GET keyword for the complete list.
DEPRECATED Please use PUT On Session instead.
Send a PUT request on the session object found using the given alias
alias that will be used to identify the Session object in the cache
uri to send the PUT request to
data a dictionary of key-value pairs that will be urlencoded and sent as PUT data or binary data that is sent as the raw body content or file descriptor retrieved by Get File For Streaming Upload
json a value that will be json encoded and sent as PUT data if data is not specified
headers a dictionary of headers to use with the request
allow_redirects Boolean. Set to True if POST/PUT/DELETE redirect following is allowed.
params url parameters to append to the uri
timeout connection timeout
Fails if response status code is a client or server error (4xx, 5xx).
response is the output of other requests keywords like GET On Session. If omitted the last response will be used.
In case of failure an HTTPError will be automatically raised.
For a more versatile assert keyword see Status Should Be.
Return True if the session has been already created
alias that has been used to identify the Session object in the cache
Fails if response status code is different than the expected.
expected_status could be the code number as an integer or as string. But it could also be a named status code like 'ok', 'created', 'accepted' or 'bad request', 'not found' etc.
response is the output of other requests keywords like GET or GET On Session. If omitted the last response will be used.
In case of failure an HTTPError will be automatically raised. A custom failure message msg can be added like in built-in keywords.
New requests keywords like GET or GET On Session (starting from 0.8 version) already have an implicit assert mechanism that, by default, verifies the response status code. Status Should Be keyword can be useful when you disable implicit assert using expected_status=anything.
For example when you have a nested keyword that is used for both OK and ERROR responses:
* Test Cases *
Test Get Request And Make Sure Is A 404 Response
${resp}= GET Custom Keyword That Returns OK or ERROR Response case=notfound
Status Should Be 404 ${resp}
Should Be Equal As Strings NOT FOUND ${resp.reason}
Test Get Request And Make Sure Is OK
${resp}= GET Custom Keyword That Returns OK or ERROR Response case=pass
Status Should Be 200 ${resp}
Should Be Equal As Strings OK ${resp.reason}
* Keywords *
GET Custom Keyword That Returns OK or ERROR Response
[Arguments] $case
[...]
IF $case == notfound
$resp= GET [...] expected_status=Anything
[Return] $resp
ELSE
[...]
DEPRECATED Please use ${resp.json()} instead. Have a look at the improved HTML output as pretty printing replacement.
Convert a string to a JSON object
content String content to convert into JSON
pretty_print If defined, will output JSON is pretty print format
Updates HTTP Session Headers and Cookies.
Session will be identified using the alias name. Dictionary of headers and cookies to be updated and merged into session data.