CORS Functional Tests
=====================

`Cross Origin Resource Sharing <https://www.w3.org/TR/cors/>`__ is a bit
of a complicated beast. It focuses on the interactions between

* a **user-agent** (typically a web browser),
* a "**source origin**" server (whose code the user-agent is running), and
* some **other server** (for our purposes, usually Swift).

Where it gets hairy is that there may be varying degrees of trust between
these different actors.

Fortunately, Swift `allows per-container configuration
<https://docs.openstack.org/swift/latest/cors.html>`__ of many CORS options.
However, our normal functional tests only exercise bits and pieces of CORS,
without telling a complete story or performing a true end-to-end test. *These*
tests aim to remedy that.

The tests consist of three parts:

* setup
    Create several test containers with well-known names, set appropriate
    ACLs and CORS metadata, and upload some test objects.

* serve
    Serve a static website on localhost which, on load, will make several
    CORS requests and verify expected behavior.

* run
    Use Selenium to load the website, wait for and scrape the results, and
    output them in `TAP format <http://testanything.org/tap-specification.html>`__.
    Alternatively, open the page in your local browser and manually inspect whether
    tests passed or failed.

All of this is orchestrated through ``main.py``. It uses the standard ``OS_*``
environment variables to determine how to connect to Swift:

* ``OS_AUTH_URL`` (or ``ST_AUTH``)
* ``OS_USERNAME`` (or ``ST_USER``)
* ``OS_PASSWORD`` (or ``ST_KEY``)
* ``OS_STORAGE_URL`` (optional)

..
   TODO: verify that this works with Keystone

Running Tests Manually
----------------------

To inspect the test results in your local browser, run::

   $ ./test/cors/main.py --no-run

This will create some test containers and object in Swift, start a simple
static site, and emit a URL to visit to run the tests, like::

   Serving test at http://localhost:8000/#OS_AUTH_URL=http://saio/auth/v1.0&OS_USERNAME=test:tester&OS_PASSWORD=testing&OS_STORAGE_URL=http://saio/v1/AUTH_test

.. note::
   You can use ``--hostname`` and ``--port`` to adjust the origin used.

Open the link. Toward the top of the page will be a status line; it will cycle
through the following states:

* Loading
* Starting jobs
* Waiting for jobs to finish
* Complete

When complete, it will also include a summary of the number of tests run as
well as pass/fail/skip counts. Below the status line will be a table of
individual tests with status, description, and additional information.

You can also run a single test by adding a ``&test=<name>`` query parameter.
For example::

   http://localhost:8000/#OS_AUTH_URL=http://saio/auth/v1.0&OS_USERNAME=test:tester&OS_PASSWORD=testing&OS_STORAGE_URL=http://saio/v1/AUTH_test&test=object%20-%20GET

will just run the test named ``object - GET``.

To stop the server, press ``^C``.

Running Tests with Selenium
---------------------------

`Selenium <https://www.selenium.dev/>`__ may be used to automate visiting the
static site, waiting for tests to run, and gathering results. See the
`installation instructions <https://selenium-python.readthedocs.io/installation.html>`__
for the Python bindings for more information about setting this up.

.. note::
   On Linux, you may want to use ``xvfb-run`` to have browsers use a virtual
   display.

When using selenium, the test runner will try to run tests in Firefox, Chrome,
Safari, Edge, and IE if available; if a browser seems to not be available, its
tests will be skipped.