===================
Webdav client tests
===================

The Webdav component provides a dedicated PHPUnit test case class, which is
capable of emulating requests send by a specific WebDAV client program and
compare the responses generated by the Webdav server. The client test case is
located in Webdav/test/client_test.php. To create tests for a new client or
re-generate tests for an existing client you need to perform the following
steps:

- Setup a test server.
- Perform tests on the server with the desired client.
- Copy the generated test logs.
- Create a client test case class (only for new clients)

-------------------
Setup a test server
-------------------

The Webdav component already ships with the necessary parts to setup a test
server. The necessary files can be found in Webdav/tests/scripts/:

- test_generator.php

  This file contains the main class for test generation. You need to require
  it manually in your test setup and instantiate it.

- test_generator_backend.php

  This file contains a configuration for an ezcWebdavMemoryBackend, which will
  be used by the test_generator.php, if no back end is already stored from
  previous requests.

To setup the test server create a new virtual host in the web server of your
choice. In the web root of this host, create an index.php and 2 directories:

- log/
- tmp/

Both must be writeable for the web server. log/ will contain the test log,
while tmp/ will be used to store information between requests (the current
request number and the serialized back end).

The index.php should look somewhat like this::

	<?php

	ini_set(
		'include_path',
		'/path/to/your/ezcomponents/trunk:.'
	);

	require_once 'Base/src/base.php';


	function __autoload( $className )
	{
		ezcBase::autoload( $className );
	}

	require_once 'Webdav/tests/scripts/test_generator.php';

	$generator = new ezcWebdavClientTestGenerator(
		// '',
        // true
	);

	$generator->run();
	$generator->store();

	?>

First, set your include_path directive according to your eZ Components trunk
checkout and initialize the auto loading. After that, require the test generator
class and instantiate it. The constructor can receive 2 options. The first is
the URI base used in your environment. This is only necessary if your don't use
the generator in the virtual web root (not recommended!). The second parameter
allows you to store the state of the test back end after each request, for
debugging purposes.

.. note:: It is not recommended to generate test files when the test generator
          does not reside in the virtual host root! Most clients to not support
          such setups.

The test generator will initialize a server and adjust all of its
configurations. The method run() will make the server run and store() will make
the test generator store all log information.

-------------
Perform tests
-------------

To test the setup at all you should first use a standard web browser and point
it to http://<virtual-host>/collection/file.html. If you see any error
messages instead of a very simple HTML file, make sure to fix these before
accessing the server with a real WebDAV client.

Now go an test with your client as desired. There are 2 different areas in the
server. The base directory and collection/ do not require authentication, the
secure_collection/ directory does. It might be necessary to re-connect to the
server with secure_collection/ as the base dir for some clients.

If you experience any problems, please try to create a debug log in a
minimalistic scenario. If the tests run smooth, please go on creating a set of
correct client tests.

Debugging
=========

For debugging it is generally recommended to switch the debugging parameter of
the test generators ctor to true. If you discover an error, proceed as follows:

1. Delete all content of log/ and tmp/ to reset the environment.
2. Switch debug mode in ezcWebdavClientTestGenerator::__construct() on.
3. Connect to the server with your client.
4. Reproduce the error with as few steps as possible.
5. Disconnect.

You will then find a complete log of all requests, responses and errors, as
well as a dump of the back end for each request in the log/ folder. Each
request/response cycle has a unique number, starting with 001. The files stored
for each request/response cycle are named like this:

- xxx_error.php

  Any errors (exceptions as well as PHP warnings, notices and fatals) will be
  exported to this file, if any occur.

- xxx_request_server.php

  An export of the $_SERVER array. Only relevant data is kept in this array,
  typical environment data is stripped. The REQUEST_TIME, REMOTE_ADDR and
  REMOTE_PORT are set to unified values.

- xxx_request_body.xml

  A plain text dump of the request body. Might be empty or contain binary data,
  not only XML.

- xxx_response_headers.php

  An export of the headers that have been send by the server.

- xxx_response_body.xml.

  A plain text dump of the body part that has been send by the server (may also
  be binary data or empty, no necessarily XML).
 
- xxx_response_status.txt

  The status code sent by the server.

- xxx_backend.ser

  A serialized version of the back end after the request has been processed.
  There is a script in Webdav/tests/scripts/visualize_serialized.php to
  visualize these dumps. Just call it with the file to visualize as the first
  parameter (and possibly pipe it to less).
  
You should inspect the \*_error_\*.php files first to see if the client
produced any mess in the server. If this is not the case, the client may need
special adjustments since it does not behave in an RFC conform way. You can try
to examine the affected request/response data to trace down where the issue
resides.

.. note:: You should open a bug on http://issues.ez.no for each error you
          discover with a client. Please attach a compressed archive (preferred
          tar.bz2) of your log/ directory to the issue.
        
Generating a test run
=====================

If your client seems to run smooth with the Webdav server, you should consider
to create a full test run to integrate it into the test Webdav component suite.
Such a client test helps us to keep track of regressions during further
development. The client tests are run in a setup very similar to the client
test generation, replaying the requests in order and comparing the responses.

To create a usable client test suite, perform the following steps:

1. Disconnect your client.
2. Delete all content from log/ and tmp/.
3. Switch of debugging in the index.php if you have it on.
4. Connect your client.
5. Follow the test recipe (below).
6. Disconnect your client.
7. Shut down your web server.

To standardize the client tests in some way and to make sure that all important
functionality is tested, please follow the mandatory test recipe.

Mandatory test recipe
---------------------

- Connect to the server without any user name and password.

- List root directory.
  
  - Make sure that all files and directories are visible:
    
    - collection/
    - file.xml
    - file.bin

    You should possibly also /secure_collection/ but with a hint that access is
    forbidden for you.
    
    IE 6 and 7 do not display the files, but only the collection. They
    are generally not capable of handling files in the document root. IE 8 on
    Windows 7 handles this properly.

- Enter directory /collection/.
- List directory.

  - Make sure that all files and directories are visible:

    - subdir/
    - file.txt

- Download file.txt to your local machine.

  - Verify that the content is "Some content".

- Enter directory /collection/subdir/

- Create a new directory /collection/subdir/newdir and make sure it was
  created.

- Enter directory /collection/subdir/newdir/.

- Upload file.txt and make sure it is there.

- Create a new directory /collection/subdir/newdir/newsubdir and enter it.

- Upload file.txt and make sure it is there.

- Upload file.txt again and make sure it is overwritten.

- Go 2 levels up to directory /collection/subdir.

- Delete newdir/ and make sure it is gone.

- Download file.html and make sure its content is
  "<html><body><h1>Test</h1></body></html>".

- Download file.xml and make sure its content is
  "<?xml?>\n<content/>".

- Delete file.html and file.xml and make sure they are gone.

- Upload all files from Webdav/tests/data/put_test/ and verify they appear
  correctly in your client.

- Upload the directory Webdav/tests/data/put_test/collection, if your server
  supports recursive uploading, and verify it appears correctly in your client.

- Download all uploaded files to a different directory and verify their
  contents against the originally.

- Rename put_test.html to put_test_renamed.xml and check that the client
  displays the change properly.

- Rename put_test_utf8_content.txt to put_test_öäüß.txt (or similar, must only
  contain UTF-8 chars) and check that the client displays the change properly.

- Rename put_test_utf8_filename_ςңα⊁∭⋉€₱‱⁌.txt to put_non_utf8_test.txt and
  check that the client displays it properly.

- Copy the uploaded and renamed files to /collection/.

- Rename /collection/ to /renamed_collection/.

- Copy /renamed_collection/ to /collection/.

- Delete /renamed_collection/.

If you performed all actions successfully, try to perform the same actions under
secure_collection/ using the user name "some" and "thing". Your client might
require you to re-connect with these credentials, since it does not recognize
secure_collection/ at all.

Optional test recipe
--------------------

Most clients will only support the steps of the recipe above. Anyway, some
clients like Cadaver support WebDAV fully and you will be able to perform the
following information:

- Read all properties from a file.

- Add the property "foobar" to a file with value 2342.

- Read all properties and check foobar is there with the appropriate value.

- Read property foobar on its own and check its value.

- Get a list of all property names and check foobar is there.

- Remove property foobar.

- List all properties and check foobar is gone.

... more to come.

----------------------------
Copy the generated test logs
----------------------------

Before you proceed with the following steps, please check the log/ directory
for \*error.php and \*backend.ser files. If you find any, the test run is
invalid! See debugging section, above!

If you generated a client test log as described above, you can integrate this
into the Webdav test suite. If you don't have commit access to the eZ
Components SVN, please open an issue on http://issues.ez.no for it. Make sure
to provide the following information in the issue:

- Operating system + version
- Client name + exact version

In addition, attach the following files to your issue:

- Compressed archive of log/ (preferred tar.bz2)
- index.php

In case you have commit access to the eZ Components SVN you can add the client
test yourself. If you re-generated a test run for an existing client test, you
can skip the first following section.

Creating a test case
====================

If you used the normal test generator and did not perform any adjustments
(highly recommended!), you should copy an existing client test case and adjust
it to your need.

1. Copy Webdav/tests/client_test_cadaver.php to
   Webdav/tests/client_test_<your client>.php.

2. Open Webdav/tests/client_test_<your_client>.php in a text editior and
replace Cadaver with <YourClientName> everywhere.

3. Open Webdav/test/suite.php in a text editor. Add the necessary require
   statement. Add the necessary addTest() call.

Adding the test log
===================

In case you are updating an existing client test, you should first delete the
old log::

    $ svn rm Webdav/tests/clients/<your_client>/*
    $ svn ci Webdav/tests/clients/<your_client>/

Please note in the commit message that you are only removing these files
temporary and that a new log will be added soon.

If you are creating a new client test, create the according directory for your
test log: Webdav/tests/clients/<your_client>/.

Now copy the content of the log/ directory of your test run to the client test
directory.

Run

::

    $ php UnitTest/src/runtests.php Webdav

and make sure that your new client test appears and runs smoothly.

Add the new files to SVN::

    $ svn add Webdav/tests/clients/<your_client>/*
    $ svn ci Webdav/tests/clients/<your_client>/

Thank you for helping to test the Webdav component! :)


..
   Local Variables:
   mode: rst
   fill-column: 79
   End: 
   vim: et syn=rst tw=79