WebTest

https://docs.pylonsproject.org/projects/webtest/en/latest/
Admin
WebTest is a Python library for functional testing of WSGI-based web applications without starting...
Tokens:46,593
Snippets:359
Trust Score:10
Update:6 months ago
Show doc for...
Tokens:
Raw
### Install WebTest using easy_install

Source: https://docs.pylonsproject.org/projects/webtest/en/latest/index.html

Use easy_install to install the latest stable release of WebTest.

```bash
$ easy_install WebTest
```

--------------------------------

### Install WebTest using pip

Source: https://docs.pylonsproject.org/projects/webtest/en/latest/index.html

Use pip to install the latest stable release of WebTest.

```bash
$ pip install WebTest
```

--------------------------------

### Install WebTest using pip or easy_install

Source: https://docs.pylonsproject.org/projects/webtest/en/latest/_sources/index.rst.txt

Use pip or easy_install to install the latest stable release of WebTest.

```sh
$ pip install WebTest
$ easy_install WebTest
```

--------------------------------

### Install and Run tox for Multi-Version Testing

Source: https://docs.pylonsproject.org/projects/webtest/en/latest/_sources/contributing.rst.txt

Install tox and use it to run tests across multiple Python versions. Ensure you have the required Python interpreters installed and available in your PATH.

```bash
$ pip install tox
$ tox
```

```bash
$ bin/tox
```

--------------------------------

### Install WebTest development version

Source: https://docs.pylonsproject.org/projects/webtest/en/latest/_sources/index.rst.txt

Install the development version of WebTest directly from its GitHub repository.

```sh
$ pip install https://nodeload.github.com/Pylons/webtest/tar.gz/main
```

--------------------------------

### Initialize WebTest Debug App

Source: https://docs.pylonsproject.org/projects/webtest/en/latest/_sources/forms.rst.txt

Setup a test application instance for form testing.

```python
>>> from webtest.debugapp import make_debug_app
>>> from webtest.app import TestApp
>>> app = make_debug_app({},
...                      form='docs/form.html',
...                      show_form=True)
>>> app = TestApp(app)
```

--------------------------------

### Initialize TestApp with WSGI application

Source: https://docs.pylonsproject.org/projects/webtest/en/latest/_sources/testapp.rst.txt

Setup a TestApp instance using a sample WSGI application that handles various content types.

```python
import json
import sys
from webtest.app import TestApp
from webob import Request
from webob import Response
def application(environ, start_response):
    req = Request(environ)
    if req.path_info.endswith('.html'):
        content_type = 'text/html'
        body = '<html><body><div id="content">hey!</div></body>'.encode('latin-1')
    elif req.path_info.endswith('.xml'):
        content_type = 'text/xml'
        body = '<xml><message>hey!</message></xml>'.encode('latin-1')
    elif req.path_info.endswith('.json'):
        content_type = 'application/json'
        body = json.dumps({"a": 1, "b": 2}).encode('latin-1')
    elif '/resource/' in req.path_info:
        content_type = 'application/json'
        body = json.dumps(dict(id=1, value='value')).encode('latin-1')
    resp = Response(body, content_type=content_type)
    return resp(environ, start_response)
app = TestApp(application)
```

--------------------------------

### Perform GET Request

Source: https://docs.pylonsproject.org/projects/webtest/en/latest/_modules/webtest/app.html

Executes a GET request with optional parameters, headers, and environment overrides.

```python
def get(self, url, params=None, headers=None, extra_environ=None,
            status=None, expect_errors=False, xhr=False):
        """
        Do a GET request given the url path.

        :param params:
            A query string, or a dictionary that will be encoded
            into a query string.  You may also include a URL query
            string on the ``url``.
        :param headers:
            Extra headers to send.
        :type headers:
            dictionary
        :param extra_environ:
            Environmental variables that should be added to the request.
        :type extra_environ:
            dictionary
        :param status:
            The HTTP status code you expect in response (if not 200 or 3xx).
            You can also use a wildcard, like ``'3*'`` or ``'*'``.
        :type status:
            integer or string
        :param expect_errors:
            If this is False, then if anything is written to
            environ ``wsgi.errors`` it will be an error.
            If it is True, then non-200/3xx responses are also okay.
        :type expect_errors:
            boolean
        :param xhr:

```

--------------------------------

### Generate Documentation with Sphinx

Source: https://docs.pylonsproject.org/projects/webtest/en/latest/_sources/contributing.rst.txt

Install Sphinx and generate HTML documentation for the project. Navigate to the docs directory and use make html or sphinx-build.

```bash
$ pip install Sphinx
$ cd docs
$ make html
```

```bash
../bin/sphinx-build -b html -d _build/doctrees   . _build/html
```

--------------------------------

### Find a Free Port

Source: https://docs.pylonsproject.org/projects/webtest/en/latest/_modules/webtest/http.html

Use this function to get an available IP address and port for binding a socket. It's useful for dynamically starting servers without port conflicts.

```python
import socket
import os

def get_free_port():
    s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
    s.bind(('', 0))
    ip, port = s.getsockname()
    s.close()
    ip = os.environ.get('WEBTEST_SERVER_BIND', '127.0.0.1')
    return ip, port
```

--------------------------------

### GET /path

Source: https://docs.pylonsproject.org/projects/webtest/en/latest/testapp.html

Performs a GET request to the specified path with optional parameters, headers, and environment variables.

```APIDOC
## GET /path

### Description
Performs a GET request to the specified path. Returns a TestResponse object.

### Method
GET

### Endpoint
/path

### Parameters
#### Query Parameters
- **params** (dict) - Optional - Query parameters for the request
- **headers** (dict) - Optional - HTTP headers
- **extra_environ** (dict) - Optional - WSGI environment keys

### Response
#### Success Response (200)
- **TestResponse** (object) - A response object based on webob.response.Response
```

--------------------------------

### Make HTTP requests

Source: https://docs.pylonsproject.org/projects/webtest/en/latest/_sources/testapp.rst.txt

Perform GET and POST requests using the TestApp instance.

```python
app.get('/path', [params], [headers], [extra_environ], ...)
```

```python
app.post('/path', {'vars': 'values'}, [headers], [extra_environ],
         [upload_files], ...)
```

--------------------------------

### Perform OPTIONS and HEAD Requests

Source: https://docs.pylonsproject.org/projects/webtest/en/latest/_modules/webtest/app.html

Methods for executing OPTIONS and HEAD requests, mirroring the behavior of the standard GET method.

```python
    def options(self, url, headers=None, extra_environ=None,
                status=None, expect_errors=False, xhr=False):
        """
        Do a OPTIONS request. Similar to :meth:`~webtest.TestApp.get`.

        :returns: :class:`webtest.TestResponse` instance.

        """
        if xhr:
            headers = self._add_xhr_header(headers)
        return self._gen_request('OPTIONS', url, headers=headers,
                                 extra_environ=extra_environ, status=status,
                                 upload_files=None,
                                 expect_errors=expect_errors)
```

```python
    def head(self, url, params=None, headers=None, extra_environ=None,
             status=None, expect_errors=False, xhr=False):
        """
        Do a HEAD request. Similar to :meth:`~webtest.TestApp.get`.

        :returns: :class:`webtest.TestResponse` instance.

        """
        if params:
            url = utils.build_params(url, params)
        if xhr:
            headers = self._add_xhr_header(headers)
        return self._gen_request('HEAD', url, headers=headers,
                                 extra_environ=extra_environ, status=status,
                                 upload_files=None,
                                 expect_errors=expect_errors)
```

--------------------------------

### Perform GET request and check response status

Source: https://docs.pylonsproject.org/projects/webtest/en/latest/_sources/index.rst.txt

Make an HTTP GET request to the root path ('/') of the wrapped application and assert the response status code and string.

```python
resp = app.get('/')
assert resp.status == '200 OK'
assert resp.status_int == 200
```

--------------------------------

### GET Request Method

Source: https://docs.pylonsproject.org/projects/webtest/en/latest/api.html

Performs a GET request.

```APIDOC
## GET Request

### `get(url, params=None, headers=None, extra_environ=None, status=None, expect_errors=False, xhr=False)`

#### Description
Do a GET request given the url path.

#### Parameters
- **url** (string) - Required - The URL path for the request.
- **params** (string or dict) - Optional - A query string, or a dictionary that will be encoded into a query string. You may also include a URL query string on the `url`.
- **headers** (dict) - Optional - Extra headers to send.
- **extra_environ** (dict) - Optional - Environmental variables to add to the request.
- **status** (integer or string) - Optional - The expected HTTP status code (if not 200 or 3xx). You can also use a wildcard, like `'3*'` or `'*'`. 
- **expect_errors** (boolean) - Optional - If this is False, then if anything is written to environ `wsgi.errors` it will be an error. If it is True, then non-200/3xx responses are also okay.
- **xhr** (boolean) - Optional - If this is true, then marks response as ajax. The same as headers={'X-REQUESTED-WITH': 'XMLHttpRequest', }.

#### Returns
`webtest.TestResponse` instance.
```

--------------------------------

### Perform a GET Request

Source: https://docs.pylonsproject.org/projects/webtest/en/latest/api.html

Performs a GET request to the specified URL. Supports query parameters, custom headers, and environment variables.

```python
resp = app.get('/users', params={'limit': 10}, headers={'X-Custom': 'value'})

```

--------------------------------

### Perform an OPTIONS Request

Source: https://docs.pylonsproject.org/projects/webtest/en/latest/api.html

Performs an OPTIONS request to the specified URL. Similar to the get() method.

```python
resp = app.options('/users')

```

--------------------------------

### Test Across Python Versions with Tox

Source: https://docs.pylonsproject.org/projects/webtest/en/latest/contributing.html

Install and execute tests across multiple Python versions using tox.

```bash
$ pip install tox
$ tox
```

```bash
$ bin/tox
py26: commands succeeded
py27: commands succeeded
py32: commands succeeded
py33: commands succeeded
```

--------------------------------

### GET / (Generic Response Inspection)

Source: https://docs.pylonsproject.org/projects/webtest/en/latest/_sources/testresponse.rst.txt

Retrieves a response object from the application and demonstrates how to inspect its status, headers, and body content.

```APIDOC
## GET /

### Description
Retrieves a response from the application. The returned object provides attributes for inspecting status, headers, and body content.

### Method
GET

### Endpoint
/

### Response
#### Success Response (200)
- **status** (string) - The text status of the response (e.g., "200 OK").
- **status_int** (integer) - The integer status code (e.g., 200).
- **headers** (dict) - A dictionary-like object of response headers.
- **body** (string) - The raw text body of the response.
- **text** (string) - The unicode text body of the response.

#### Response Example
{
  "status": "200 OK",
  "status_int": 200,
  "body": "<html><body><div id=\"content\">hey!</div></body>"
}
```

--------------------------------

### Perform HTTP GET request

Source: https://docs.pylonsproject.org/projects/webtest/en/latest/index.html

Make an HTTP GET request to the root path of the wrapped WSGI application using TestApp.

```python
resp = app.get('/')
```

--------------------------------

### Execute a Request with TestApp

Source: https://docs.pylonsproject.org/projects/webtest/en/latest/api.html

Executes a pre-constructed webob Request object. Useful for more complex request setups.

```python
req = webtest.TestRequest.blank('url', ...args...)
resp = app.do_request(req)

```

--------------------------------

### Define a basic WSGI application

Source: https://docs.pylonsproject.org/projects/webtest/en/latest/_sources/index.rst.txt

A simple WSGI application that returns a predefined HTML body. This is used as an example to be wrapped by WebTest's TestApp.

```python
def application(environ, start_response):
    headers = [('Content-Type', 'text/html; charset=utf8'),
               ('Content-Length', str(len(body)))]
    start_response('200 OK', headers)
    return [body]
```

--------------------------------

### Perform a HEAD Request

Source: https://docs.pylonsproject.org/projects/webtest/en/latest/api.html

Performs a HEAD request to the specified URL. Similar to the get() method.

```python
resp = app.head('/users')

```

--------------------------------

### Internal Request Handling Logic

Source: https://docs.pylonsproject.org/projects/webtest/en/latest/_modules/webtest/app.html

Internal implementation details for request processing, including environment setup and header management.

```python
        environ = self._make_environ(extra_environ)
        url = str(url)
        url = self._remove_fragment(url)
        if params:
            url = utils.build_params(url, params)
        if '?' in url:
            url, environ['QUERY_STRING'] = url.split('?', 1)
        else:
            environ['QUERY_STRING'] = ''
        req = self.RequestClass.blank(url, environ)
        if xhr:
            headers = self._add_xhr_header(headers)
        if headers:
            req.headers.update(headers)
        return self.do_request(req, status=status,
                               expect_errors=expect_errors)
```

--------------------------------

### GET Authorization

Source: https://docs.pylonsproject.org/projects/webtest/en/latest/api.html

Retrieves the HTTP_AUTHORIZATION environment key value.

```APIDOC
## GET Authorization

### `get_authorization()`

#### Description
Allow to set the HTTP_AUTHORIZATION environ key. Value should look like one of the following:
  * `('Basic', ('user', 'password'))`
  * `('Bearer', 'mytoken')`
  * `('JWT', 'myjwt')`

If value is None the the HTTP_AUTHORIZATION is removed.
```

--------------------------------

### Navigate to URL

Source: https://docs.pylonsproject.org/projects/webtest/en/latest/_modules/webtest/response.html

Navigates to a given URL, ignoring scheme, host, and fragment. It joins the provided href with the current request URL to resolve relative paths. Supports 'get' or 'post' methods and passes additional arguments to the underlying request method.

```python
scheme, host, path, query, fragment = urlparse.urlsplit(href)
```

```python
scheme = host = fragment = ''
href = urlparse.urlunsplit((scheme, host, path, query, fragment))
```

```python
href = urlparse.urljoin(self.request.url, href)
```

```python
method = method.lower()
        assert method in ('get', 'post'), (
```

--------------------------------

### Getting Parsed XML with lxml

Source: https://docs.pylonsproject.org/projects/webtest/en/latest/testresponse.html

Use `response.lxml` to get the response body parsed by the `lxml` library, enabling XPath queries. This requires `lxml` to be installed. An `AttributeError` is raised if the content-type is incorrect.

```python
>>> res = app.get('/index.html')
>>> res.lxml
<Element html at ...>
>>> res.lxml.xpath('//body/div')[0].text
'hey!'

>>> res = app.get('/document.xml')
>>> res.lxml
<Element xml at ...>
>>> res.lxml[0].tag
'message'
>>> res.lxml[0].text
'hey!'
```

--------------------------------

### Clone and Set Up webtest Project

Source: https://docs.pylonsproject.org/projects/webtest/en/latest/_sources/contributing.rst.txt

Clone the webtest repository and set up a virtual environment for development. This is the initial step for contributing to the project.

```bash
$ git clone https://github.com/Pylons/webtest.git
$ cd webtest
$ virtualenv .
$ . bin/activate
$ python setup.py dev
```

--------------------------------

### Initialize TestApp with different backends

Source: https://docs.pylonsproject.org/projects/webtest/en/latest/_sources/testapp.rst.txt

Demonstrates how to instantiate TestApp using specific request backends.

```python
app = TestApp('http://my.cool.websi.te#requests')
```

```python
app = TestApp('http://my.cool.websi.te#restkit')
```

--------------------------------

### Initialize and use debug_app

Source: https://docs.pylonsproject.org/projects/webtest/en/latest/debugapp.html

Demonstrates how to wrap the debug_app with TestApp and inspect the request environment.

```python
>>> import webtest
>>> from webtest.debugapp import debug_app
>>> app = webtest.TestApp(debug_app)
>>> res = app.post('/', params='foobar')
>>> print(res.body) 
CONTENT_LENGTH: 6
CONTENT_TYPE: application/x-www-form-urlencoded
HTTP_HOST: localhost:80
...
wsgi.url_scheme: 'http'
wsgi.version: (1, 0)
-- Body ----------
foobar
```

--------------------------------

### Initialize Upload object

Source: https://docs.pylonsproject.org/projects/webtest/en/latest/_modules/webtest/forms.html

Demonstrates creating an Upload instance for file submission.

```python
>>> Upload('filename.txt', 'data', 'application/octet-stream')
<Upload "filename.txt">
>>> Upload('filename.txt', 'data')
<Upload "filename.txt">
>>> Upload("README.txt")
<Upload "README.txt">
```

--------------------------------

### Generate Documentation with Sphinx

Source: https://docs.pylonsproject.org/projects/webtest/en/latest/contributing.html

Build the project documentation using Sphinx.

```bash
$ pip install Sphinx
$ cd docs
$ make html
../bin/sphinx-build -b html -d _build/doctrees   . _build/html
Running Sphinx v1.1.3
loading pickled environment... done

...

build succeeded, 3 warnings.

Build finished. The HTML pages are in _build/html.
```

--------------------------------

### goto

Source: https://docs.pylonsproject.org/projects/webtest/en/latest/_modules/webtest/response.html

Navigates to a specified URL using a defined HTTP method.

```APIDOC
## goto

### Description
Navigates to the provided relative or absolute URL using GET or POST methods.

### Parameters
#### Query Parameters
- **href** (string) - Required - The target URL to navigate to.
- **method** (string) - Optional - The HTTP method to use ('get' or 'post'). Defaults to 'get'.
```

--------------------------------

### Instantiate TestApp

Source: https://docs.pylonsproject.org/projects/webtest/en/latest/api.html

Wraps a WSGI application for testing. Supports extra environment variables, relative paths, and cookie handling.

```python
app = webtest.TestApp(my_wsgi_app, extra_environ={'REMOTE_ADDR': '127.0.0.1'})

```

--------------------------------

### Request Methods API

Source: https://docs.pylonsproject.org/projects/webtest/en/latest/_modules/webtest/app.html

Provides methods for performing HTTP requests such as GET.

```APIDOC
## GET /

### Description
Performs a GET request to the specified URL.

### Method
GET

### Endpoint
/

### Parameters
#### Query Parameters
- **url** (string) - Required - The URL path to request.
- **params** (object or string) - Optional - Query string parameters or a dictionary to be encoded into a query string.
- **headers** (object) - Optional - Extra headers to send with the request.
- **extra_environ** (object) - Optional - Environmental variables to add to the request.
- **status** (integer or string) - Optional - The expected HTTP status code (e.g., 200, '3*', '*').
- **expect_errors** (boolean) - Optional - If False, errors written to wsgi.errors will cause an exception. If True, non-200/3xx responses are also considered okay.
- **xhr** (boolean) - Optional - Indicates if the request is an XMLHttpRequest.

### Response
#### Success Response (200)
- **body** (string) - The response body.
- **status_code** (integer) - The HTTP status code of the response.
- **headers** (object) - The response headers.

#### Response Example
```json
{
  "body": "<html><body>Hello World</body></html>",
  "status_code": 200,
  "headers": {
    "Content-Type": "text/html"
  }
}
```
```

--------------------------------

### Environment Configuration

Source: https://docs.pylonsproject.org/projects/webtest/en/latest/_modules/webtest/app.html

Creates a WSGI environment dictionary with default settings and optional overrides.

```python
    def _make_environ(self, extra_environ=None):
        environ = self.extra_environ.copy()
        environ['paste.throw_errors'] = True
        if extra_environ:
            environ.update(extra_environ)
        return environ
```

--------------------------------

### Initialize TestApp

Source: https://docs.pylonsproject.org/projects/webtest/en/latest/_modules/webtest/app.html

Initialize TestApp to wrap a WSGI application for testing. It can accept a WSGI application, a Paste Deploy URI, or a full URL for proxying. Configuration options include extra environment variables, relative path for file uploads, and cookie handling.

```python
def __init__(self, app, extra_environ=None, relative_to=None,
             use_unicode=True, cookiejar=None, parser_features=None,
             json_encoder=None, lint=True):

    if 'WEBTEST_TARGET_URL' in os.environ:
        app = os.environ['WEBTEST_TARGET_URL']
    if isinstance(app, str):
        if app.startswith('http'):
            try:
                from wsgiproxy import HostProxy
            except ImportError:
                raise ImportError(
                    'Using webtest with a real url requires WSGIProxy2. '
                    'Please install it with: '
                    'pip install WSGIProxy2')
            if '#' not in app:
                app += '#httplib'
            url, client = app.split('#', 1)
            app = HostProxy(url, client=client)
        else:
            from paste.deploy import loadapp
            app = loadapp(app, relative_to=relative_to)
    self.app = app
```

--------------------------------

### Perform a DELETE Request

Source: https://docs.pylonsproject.org/projects/webtest/en/latest/api.html

Performs a DELETE request to the specified URL. Similar to the get() method.

```python
resp = app.delete('/users/1')

```

--------------------------------

### TestApp Initialization

Source: https://docs.pylonsproject.org/projects/webtest/en/latest/api.html

Initializes the TestApp class, wrapping a WSGI application for testing purposes.

```APIDOC
## `webtest.app.TestApp`

### Description
Wraps a WSGI application in a more convenient interface for testing. It uses extended versions of `webob.BaseRequest` and `webob.Response`.

### Parameters
#### Path Parameters
- **app** (WSGI application) - Required - May be a WSGI application or Paste Deploy app, like `'config:filename.ini#test'`. It can also be an actual full URL to an http server and webtest will proxy requests with WSGIProxy2.
- **extra_environ** (dict) - Optional - A dictionary of values that should go into the environment for each request. These can provide a communication channel with the application.
- **relative_to** (string) - Optional - A directory used for file uploads are calculated relative to this. Also `config:` URIs that aren't absolute.
- **cookiejar** (CookieJar instance) - Optional - `cookielib.CookieJar` alike API that keeps cookies across requests.
- **parser_features** (string or list) - Optional - Passed to BeautifulSoup when parsing responses.
- **json_encoder** (A subclass of json.JSONEncoder) - Optional - Passed to json.dumps when encoding json.
- **lint** (boolean) - Optional - If True (default) then check that the application is WSGI compliant.
```

--------------------------------

### Handle File Upload Fields

Source: https://docs.pylonsproject.org/projects/webtest/en/latest/forms.html

Use the `Upload` class to prepare files for upload. You can specify the filename, data, and content type.

```python
>>> from webtest import Upload
>>> form['file'] = Upload('README.rst')
```

```python
>>> form['file'] = Upload('README.rst', b'data')
```

```python
>>> form['file'] = Upload('README.rst', b'data', 'text/x-rst')
```

--------------------------------

### Access XML response body

Source: https://docs.pylonsproject.org/projects/webtest/en/latest/_modules/webtest/response.html

Parses the response body as an ElementTree object. Requires ElementTree to be installed.

```python
        from xml.etree import ElementTree
        except ImportError:  # pragma: no cover
            try:
                import ElementTree
            except ImportError:
                try:
                    from elementtree import ElementTree  # NOQA
                except ImportError:
                    raise ImportError(
                        "You must have ElementTree installed "
                         "(or use Python 2.5) to use response.xml")
        # ElementTree can't parse unicode => use `body` instead of `testbody`
        return ElementTree.XML(self.body)
```

--------------------------------

### Simulate authentication

Source: https://docs.pylonsproject.org/projects/webtest/en/latest/_sources/testapp.rst.txt

Configure authentication headers or environment variables for requests.

```python
app.get('/secret', extra_environ=dict(REMOTE_USER='bob'))
```

```python
app = TestApp(my_app, extra_environ=dict(REMOTE_USER='bob'))
```

```python
app = TestApp(my_app)
app.authorization = ('Basic', ('user', 'password'))
```

```python
app = TestApp(my_app)
app.authorization = ('Bearer', 'mytoken')
# or
app.authorization = ('JWT', 'myjwt')
```

--------------------------------

### Accessing Response as XML

Source: https://docs.pylonsproject.org/projects/webtest/en/latest/_modules/webtest/response.html

Provides the response body parsed as an ElementTree XML object. Requires ElementTree to be installed.

```APIDOC
## GET /response/xml

### Description
Returns the response body parsed as an ElementTree XML object.

### Method
GET

### Endpoint
/response/xml

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **xml_object** (ElementTree.Element) - The parsed XML object.

#### Response Example
```xml
<root>
  <element>value</element>
</root>
```
```

--------------------------------

### Handle Multiple File Uploads

Source: https://docs.pylonsproject.org/projects/webtest/en/latest/forms.html

For file input fields that accept multiple files, provide a list of `Upload` objects.

```python
>>> from webtest import Upload
>>> form['files'] = [
...    Upload('README.rst'),
...    Upload('LICENSE.rst'),
... ]
```

--------------------------------

### Create and Execute a Request

Source: https://docs.pylonsproject.org/projects/webtest/en/latest/_modules/webtest/app.html

Use this method to create and execute a request. You can pass an instantiated TestRequest object or a URL with keyword arguments for TestRequest.blank. This is useful for testing custom methods like MKCOL or PUT with a body.

```python
def request(self, url_or_req, status=None, expect_errors=False,
                **req_params):
        """
        Creates and executes a request. You may either pass in an
        instantiated :class:`TestRequest` object, or you may pass in a
        URL and keyword arguments to be passed to
        :meth:`TestRequest.blank`.

        You can use this to run a request without the intermediary
        functioning of :meth:`TestApp.get` etc.  For instance, to
        test a WebDAV method::

            resp = app.request('/new-col', method='MKCOL')

        Note that the request won't have a body unless you specify it, like::

            resp = app.request('/test.txt', method='PUT', body='test')

        You can use :class:`webtest.TestRequest`::

            req = webtest.TestRequest.blank('/url/', method='GET')
            resp = app.do_request(req)

        """
        if isinstance(url_or_req, str):
            url_or_req = str(url_or_req)
        for (k, v) in req_params.items():
            if isinstance(v, str):
                req_params[k] = str(v)
        if isinstance(url_or_req, str):
            req = self.RequestClass.blank(url_or_req, **req_params)
        else:
            req = url_or_req.copy()
            for name, value in req_params.items():
                setattr(req, name, value)
        req.environ['paste.throw_errors'] = True
        for name, value in self.extra_environ.items():
            req.environ.setdefault(name, value)
        return self.do_request(req,
                               status=status,
                               expect_errors=expect_errors,
                               )
```

--------------------------------

### Manage HTTP Authorization

Source: https://docs.pylonsproject.org/projects/webtest/en/latest/_modules/webtest/app.html

Methods to get and set the HTTP_AUTHORIZATION environment variable using Basic, Bearer, or JWT schemes.

```python
def get_authorization(self):
        """Allow to set the HTTP_AUTHORIZATION environ key. Value should look
        like one of the following:

        * ``('Basic', ('user', 'password'))``
        * ``('Bearer', 'mytoken')``
        * ``('JWT', 'myjwt')``

        If value is None the the HTTP_AUTHORIZATION is removed
        """
        return self.authorization_value


    def set_authorization(self, value):
        self.authorization_value = value
        if value is not None:
            invalid_value = (
                "You should use a value like ('Basic', ('user', 'password'))"
                " OR ('Bearer', 'token') OR ('JWT', 'token')"
            )
            if isinstance(value, (list, tuple)) and len(value) == 2:
                authtype, val = value
                if authtype == 'Basic' and val and \
                   isinstance(val, (list, tuple)):
                    val = ':'.join(list(val))
                    val = b64encode(to_bytes(val)).strip()
                    val = val.decode('latin1')
                elif authtype in ('Bearer', 'JWT') and val and \
                        isinstance(val, (str, str)):
                    val = val.strip()
                else:
                    raise ValueError(invalid_value)
                value = str(f'{authtype} {val}')
            else:
                raise ValueError(invalid_value)
            self.extra_environ.update({
                'HTTP_AUTHORIZATION': value,
            })
        else:
            if 'HTTP_AUTHORIZATION' in self.extra_environ:
                del self.extra_environ['HTTP_AUTHORIZATION']

    authorization = property(get_authorization, set_authorization)
```

--------------------------------

### Handle Simple Select Fields

Source: https://docs.pylonsproject.org/projects/webtest/en/latest/forms.html

Manage single-selection dropdowns. You can get the current value and set a new option by its value.

```python
>>> print(form['select'].value)
option2
```

```python
>>> form['select'] = 'option1'
```

--------------------------------

### Initialize Form Parser

Source: https://docs.pylonsproject.org/projects/webtest/en/latest/_modules/webtest/forms.html

Instantiate the Form class with a webob.response.TestResponse and the HTML text of the form. The parser_features argument defaults to 'html.parser'.

```python
form = Form(response, text)
```

--------------------------------

### POST /

Source: https://docs.pylonsproject.org/projects/webtest/en/latest/_modules/webtest/app.html

Performs a POST request to the specified URL with optional parameters, file uploads, and headers.

```APIDOC
## POST /

### Description
Performs a POST request to the specified URL. Supports sending parameters in the body, file uploads, and custom content types.

### Method
POST

### Parameters
#### Query Parameters
- **url** (string) - Required - The target URL path.
- **params** (string/dict) - Optional - Data to be sent in the request body.
- **headers** (dict) - Optional - Custom HTTP headers.
- **upload_files** (list) - Optional - List of (fieldname, filename, file_content) tuples.
- **content_type** (string) - Optional - The HTTP content type (e.g., application/json).
- **xhr** (boolean) - Optional - If true, adds X-REQUESTED-WITH: XMLHttpRequest header.

### Response
#### Success Response (200)
- **TestResponse** (object) - Returns a webtest.TestResponse instance.
```

--------------------------------

### Get a Single Form

Source: https://docs.pylonsproject.org/projects/webtest/en/latest/forms.html

Access the single HTML form on a page using the `.form` attribute. This is suitable when only one form is present.

```python
>>> res = app.get('/form.html')
>>> form = res.form
```

--------------------------------

### Select Options by Text

Source: https://docs.pylonsproject.org/projects/webtest/en/latest/forms.html

Use `.select()` for single selects and `.select_multiple()` for multiple selects to choose options based on their visible text rather than their value attribute.

```python
>>> form['select'].select(text="Option 2")
>>> print(form['select'].value)
option2
```

```python
>>> form['multiple'].select_multiple(texts=["Option 1", "Option 2"])
>>> print(form['multiple'].value) 
['option1', 'option2']
```

--------------------------------

### Get a Form by Index or ID

Source: https://docs.pylonsproject.org/projects/webtest/en/latest/forms.html

When multiple forms exist, access them using the `.forms` property by their index or the form's ID attribute.

```python
>>> form = res.forms[0]
```

```python
>>> form = res.forms['myform']
```

--------------------------------

### Accessing Response as PyQuery Object

Source: https://docs.pylonsproject.org/projects/webtest/en/latest/_modules/webtest/response.html

Returns the response as a PyQuery object, which is useful for querying HTML and XML content. Requires PyQuery to be installed.

```APIDOC
## GET /response/pyquery

### Description
Returns the response body as a PyQuery object. This is only applicable for HTML and XML content types.

### Method
GET

### Endpoint
/response/pyquery

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **pyquery_object** (PyQuery) - The parsed PyQuery object.

#### Response Example
```html
<html><body><p class="content">Hello</p></body></html>
```
```

--------------------------------

### Get File Upload Fields

Source: https://docs.pylonsproject.org/projects/webtest/en/latest/_modules/webtest/forms.html

Returns a list of file field tuples, each containing the field name and file name, optionally with file contents.

```python
uploads = []
for name, fields in self.fields.items():
    for field in fields:
        if isinstance(field, File) and field.value:

```

--------------------------------

### Configuration API

Source: https://docs.pylonsproject.org/projects/webtest/en/latest/_modules/webtest/app.html

APIs for configuring the testing environment, such as parser features and resetting state.

```APIDOC
## PUT /parser-features

### Description
Changes the parser used by BeautifulSoup for response processing.

### Method
PUT

### Endpoint
/parser-features

### Parameters
#### Request Body
- **parser_features** (string) - Required - The name of the parser to use (e.g., 'html.parser').

### Request Example
```json
{
  "parser_features": "lxml"
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message.

#### Response Example
```json
{
  "message": "Parser features set successfully."
}
```

## POST /reset

### Description
Resets the state of the application, primarily clearing saved cookies.

### Method
POST

### Endpoint
/reset

### Response
#### Success Response (200)
- **message** (string) - Confirmation message.

#### Response Example
```json
{
  "message": "State reset successfully."
}
```
```

--------------------------------

### Handle Multiple Select Fields

Source: https://docs.pylonsproject.org/projects/webtest/en/latest/forms.html

Manage multi-selection dropdowns. You can get the current selection as a list and set new options by providing a list of values.

```python
>>> print(form['multiple'].value) 
['option2', 'option3']
```

```python
>>> form['multiple'] = ['option1']
```

--------------------------------

### Initialize TestResponse

Source: https://docs.pylonsproject.org/projects/webtest/en/latest/_modules/webtest/response.html

The TestResponse class is instantiated by TestApp methods and extends webob.Response. It includes properties for request, forms, and parser features.

```python
import re
from json import loads

from webtest import forms
from webtest import utils
from webtest.compat import print_stderr
from webtest.compat import urlparse
from webtest.compat import to_bytes

from bs4 import BeautifulSoup

import webob



class TestResponse(webob.Response):
    """
    Instances of this class are returned by
    :class:`~webtest.app.TestApp` methods.
    """

    request = None
    _forms_indexed = None
    parser_features = 'html.parser'

    @property
    def forms(
        self
    ):
        """
        Returns a dictionary containing all the forms in the pages as
        :class:`~webtest.forms.Form` objects. Indexes are both in
        order (from zero) and by form id (if the form is given an id).

        See :doc:`forms` for more info on form objects.
        """
        if self._forms_indexed is None:
            self._parse_forms()
        return self._forms_indexed

    @property
    def form(
        self
    ):
        """
        If there is only one form on the page, return it as a
        :class:`~webtest.forms.Form` object; raise a TypeError is
        there are no form or multiple forms.
        """
        forms_ = self.forms
        if not forms_:
            raise TypeError(
                "You used response.form, but no forms exist"
            )
        if 1 in forms_:
            # There is more than one form
            raise TypeError(
                "You used response.form, but more than one form exists"
            )
        return forms_[0]

    @property
    def testbody(
        self
    ):
        self.decode_content()
        if self.charset:
            try:
                return self.text
            except UnicodeDecodeError:
                return self.body.decode(self.charset, 'replace')
        return self.body.decode('ascii', 'replace')

    _tag_re = re.compile(r'<(/?)([:a-z0-9_\-]*)(.*?)>', re.S | re.I)

    def _parse_forms(
        self
    ):
        forms_ = self._forms_indexed = {}
        form_texts = [str(f) for f in self.html('form')]
        for i, text in enumerate(form_texts):
            form = forms.Form(self, text, self.parser_features)
            forms_[i] = form
            if form.id:
                forms_[form.id] = form

    def _follow(
        self,
        **kw
    ):
        location = self.headers['location']
        abslocation = urlparse.urljoin(self.request.url, location)
        # @@: We should test that it's not a remote redirect
        return self.test_app.get(abslocation, **kw)


    def follow(
        self,
        **kw
    ):
        """
        If this response is a redirect, follow that redirect.  It is an
        error if it is not a redirect response. Any keyword
        arguments are passed to :class:`~webtest.app.TestApp.get`. Returns
        another :class:`TestResponse` object.
        """
        if not (300 <= self.status_int < 400):
            raise AssertionError(
                "You can only follow redirect responses (not %s)" % self.status
            )
        return self._follow(**kw)



    def maybe_follow(
        self,
        **kw
    ):
        """
        Follow all redirects. If this response is not a redirect, do nothing.
        Any keyword arguments are passed to :class:`webtest.app.TestApp.get`.
        Returns another :class:`TestResponse` object.
        """
        remaining_redirects = 100  # infinite loops protection
        response = self

        while 300 <= response.status_int < 400 and remaining_redirects:
            response = response._follow(**kw)
            remaining_redirects -= 1

        if remaining_redirects <= 0:
            raise AssertionError("redirects chain looks infinite")

        return response



    def click(
        self,
        description=None,
        linkid=None,
        href=None,
        index=None,
        verbose=False,
        extra_environ=None
    ):
        """
        Click the link as described.  Each of ``description``, 
        ``linkid``, and ``url`` are *patterns*, meaning that they are
        either strings (regular expressions), compiled regular
        expressions (objects with a ``search`` method), or callables
        returning true or false.

        All the given patterns are ANDed together:

        * ``description`` is a pattern that matches the contents of the
          anchor (HTML and all -- everything between ``<a...>`` and
          ``</a>``)

        * ``linkid`` is a pattern that matches the ``id`` attribute of
          the anchor.  It will receive the empty string if no id is
          given.

        * ``href`` is a pattern that matches the ``href`` of the anchor;
          the literal content of that attribute, not the fully qualified
          attribute.

        If more than one link matches, then the ``index`` link is
        followed.  If ``index`` is not given and more than one link
        matches, or if no link matches, then ``IndexError`` will be
        raised.

        If you give ``verbose`` then messages will be printed about
        each link, and why it does or doesn't match.  If you use

```

--------------------------------

### Define a Test Application

Source: https://docs.pylonsproject.org/projects/webtest/en/latest/_sources/testresponse.rst.txt

Defines a simple WSGI application that serves different content types based on the request path, used for testing with TestApp.

```python
>>> import json
>>> import sys
>>> from webob import Request
>>> from webob import Response
>>> from webtest.app import TestApp
>>> def application(environ, start_response):
...     req = Request(environ)
...     if req.path_info.endswith('.html'):
...         content_type = 'text/html'
...         body = '<html><body><div id="content">hey!</div></body>'.encode('latin-1')
...     elif req.path_info.endswith('.xml'):
...         content_type = 'text/xml'
...         body = '<xml><message>hey!</message></xml>'.encode('latin-1')
...     elif req.path_info.endswith('.json'):
...         content_type = 'application/json'
...         body = json.dumps({"a": 1, "b": 2}).encode('latin-1')
...     resp = Response(body, content_type=content_type)
...     return resp(environ, start_response)
>>> app = TestApp(application)
```

--------------------------------

### Get Form Field Object

Source: https://docs.pylonsproject.org/projects/webtest/en/latest/_modules/webtest/forms.html

Retrieves a specific form field object by name. Raises an AssertionError if the field is not found or if multiple fields match the name.

```python
fields = self.fields.get(name)
assert fields is not None, (
    "No field by the name %r found" % name)
assert len(fields) == 1, (
    "Multiple fields match %r: %s"
    % (name, ', '.join(map(repr, fields))))
return fields[0]
```

--------------------------------

### Accessing Response as lxml Object

Source: https://docs.pylonsproject.org/projects/webtest/en/latest/_modules/webtest/response.html

Returns the response as an lxml object. This method is suitable for HTML and XML content types and requires the lxml library to be installed.

```APIDOC
## GET /response/lxml

### Description
Returns the response body parsed as an lxml object. This is applicable for HTML and XML content types.

### Method
GET

### Endpoint
/response/lxml

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **lxml_object** (lxml.etree._Element or lxml.html.HtmlElement) - The parsed lxml object.

#### Response Example
```html
<html><body><h1>Title</h1></body></html>
```
```

--------------------------------

### OPTIONS /url

Source: https://docs.pylonsproject.org/projects/webtest/en/latest/_modules/webtest/app.html

Performs an OPTIONS request to the specified URL.

```APIDOC
## OPTIONS /url

### Description
Performs an OPTIONS request to the specified URL.

### Method
OPTIONS

### Endpoint
/url

### Parameters
#### Query Parameters
- **url** (string) - Required - The target URL.
- **headers** (dict) - Optional - Request headers.
- **extra_environ** (dict) - Optional - Extra environment variables.
- **status** (int/str) - Optional - Expected status code.
- **expect_errors** (bool) - Optional - Whether to expect errors.
- **xhr** (bool) - Optional - Whether to add XHR headers.

### Response
#### Success Response (200)
- **response** (TestResponse) - Returns a TestResponse instance.
```

--------------------------------

### Get and Set Form Field Values

Source: https://docs.pylonsproject.org/projects/webtest/en/latest/forms.html

Retrieve the current value of a form field or set a new value. For fields with non-unique names, use `.set()` with an index.

```python
>>> print(form['text'].value)
Foo
```

```python
>>> form['text'] = 'Bar'
```

```python
>>> # When names don't point to a single field:
>>> form.set('text', 'Bar', index=0)
```

--------------------------------

### Execute Tests with Pytest

Source: https://docs.pylonsproject.org/projects/webtest/en/latest/contributing.html

Run the test suite using the local pytest binary.

```bash
$ bin/pytest
Doctest: forms.rst ... ok
Doctest: index.rst ... ok

...

test_url_class (tests.test_testing.TestTesting) ... ok
tests.test_testing.test_print_unicode ... °C
ok

Name               Stmts   Miss  Cover   Missing
------------------------------------------------
webtest               18      0   100%
webtest.app          603     92    85%   48, 61-62, 94, 98, 212-221, 264-265, 268-272, 347, 379-386, 422, 426-428, 432-434, 455, 463, 471, 473, 488, 496-497, 515, 520-527, 548, 553-554, 558-559, 577, 592, 597-598, 618, 624, 661-664, 742, 808, 872, 940-941, 945-948, 961-964, 975, 982, 995, 1000, 1006, 1010, 1049, 1051, 1095-1096, 1118-1119, 1122-1127, 1135-1136, 1148, 1155-1160, 1175
webtest.compat        50     11    78%   28-34, 55-56, 61-62
webtest.debugapp      58      0   100%
webtest.ext           80      0   100%
webtest.forms        324     23    93%   23, 49, 58, 61, 92, 116, 177, 205, 411, 478, 482-486, 491-493, 522, 538, 558-561
webtest.http          78      0   100%
webtest.lint         215     45    79%   135, 176, 214-216, 219-224, 227-231, 234, 243-244, 247, 250-251, 254, 263-264, 270, 274, 307, 311, 335, 359, 407, 424-427, 441-444, 476-479, 493, 508
webtest.sel          479    318    34%   38-39, 45-46, 64-78, 88-108, 120, 126, 151-153, 156-158, 164-165, 168-191, 194-201, 219-231, 236, 240, 243-259, 263-297, 301-306, 316-326, 331-336, 340, 344, 347-352, 357-359, 364, 392-394, 397-404, 408, 412-417, 421, 425-426, 430, 434, 438, 442, 445, 448-457, 470-480, 483-485, 488, 492, 495, 503, 506, 515-516, 520, 524, 528, 533, 538, 542-544, 547, 560-565, 576, 579, 582, 593-596, 599-602, 605-606, 617-620, 623-642, 668-677, 680-688, 715, 720, 732, 735, 744-754, 757-762, 770-779, 791, 794, 805-809, 813-826, 838-842
webtest.utils         99     11    89%   19-20, 23, 26, 32, 38, 100, 109, 152-154
------------------------------------------------
TOTAL               2004    500    75%
----------------------------------------------------------------------
Ran 70 tests in 14.940s
```

--------------------------------

### Get Form Field Object with Default

Source: https://docs.pylonsproject.org/projects/webtest/en/latest/_modules/webtest/forms.html

Retrieves a form field object by name and optional index. Returns a default value if the field is not found, otherwise raises an AssertionError.

```python
fields = self.fields.get(name)
if fields is None:
    if default is utils.NoDefault:
        raise AssertionError(
            "No fields found matching %r (and no default given)"
            % name)
    return default
if index is None:
    return self[name]
return fields[index]
```
Tokens:
Raw