eZ Components - Webdav - Client test specification
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

:Author: Kore Nordmann, Tobias Schlitt
:Revision: $Rev$
:Date: $Date$
:Status: Draft

.. contents::

Scope
=====

The scope of this document is to define how client test suits will be created
for the Webdav component of the eZ Components. The technical realization of
client test suite generation is handled by the class
ezcWebdavClientTestGenerator, contained in
Webdav/tests/scripts/test_generator.php. The purpose of this document is to
describe the necessary steps for creating a new client test suite.

Procedure
==========

This section will explain step by stepl how a new client is to be integrated
with the Webdav component.

Setup
-----

First you need to set up a test environment that logs requests and the
corresponding responses generated by the Webdav component. For this purpose a
wrapper class for ezcWebdavServer exists, which automatically mocks all known
transport classes to retrieve the desired data and creates client test suite
like log directories.

Setup a client test suite generator using ezcWebdavClientTestGenerator from
Webdav/tests/scripts/test_generator.php.

For this you need a mechnisma like mod_rewrite in place to make the path
factory working. It is recommended to use a dedicated virtual host for
testing. For additional setup information see the class documentation of the
generator.

Test the setup
--------------

Before a new client can be tested using this setup it should be verified, that
the setup works correctly. A good way to do so is to use Litmus_ and compare
the log of a testrun against the server with the logs in SVN.

.. _Litmus: http://www.webdav.org/neon/litmus/

Integration tests
-----------------

To test how well a desired client works a procedure of defined steps should be
used. The integrator must usually perform these manually and inspect the
results displayed in the client. If the result differs from the real situation
in the server or does not reflect the expectations indicated by other (working)
clients, a new ezcWebdavTransport inheriting class must be started, that
adjusts the behaviour accordingly.

Remember that you need to delete the contents of the tmp/ and log/ directories
on every restart, to use a clean environment. Otherwise the generated test
cases would behave different in the test runner. When adding a new transport
extension, this needs to be configured in the server before the generator in
instanciated to get it properly mocked for capturing.

This testing procedur must be repeated until the integrator is satisfied with
all step results and the test procedure overall, adjusting the extending
transport layer accordingly.

The following test steps define a client test suite. The actions described need
to be performed in the defined order as good as the clients features support
them. If a step is not supported at all, it may be ignored and following test
cases may be adjusted.

View /
  - Collection: "collection"
  - Files: "file.bin", "file.xml"

View /file.xml
  - Content: "<?xml ?>\n<content/>"

View /collection
  - Collection: "subdir"
  - Files: "file.txt"

Back to /

Upload put_test to /

View /
  - Collection: "collection", "put_test"
  - Files: "file.bin", "file.xml"

View /put_test
  - Collection: "collection"
  - Files: "put_test.html"

Back to /

Rename /put_test to /new_collection

Move /new_collection to /collection/new_collection

View /collection
  - Collection: "subdir", "new_collection"
  - Files: "file.txt"

Copy /collection/new_collection to /collection/uploaded

View /collection
  - Collection: "subdir", "uploaded", "new_collection"
  - Files: "file.txt"

Test suite generation
---------------------

If the client works flawlessly with all test steps, the transport
implementation (if one was needed) can be added to the default distribution.
With that, a test suite for this client is necessary, reflecting all steps
defined in the plast section. To do this take care for a clean environment
(rm -rf tmp/* log/* ) and perform all test steps, re-checking that all results
are as expected.

Create a new directory for the client in Webdav/tests/clients/, named after the
clients program name in lowercase letters. Do not use spaces, but underscores,
if necessary in the name. Copy the client_cadaver_test.php file and adjust it
to your needs and test it, using::

    $ php UnitTest/src/runtests.php Webdav/tests/client_<yourclient>_test.php

If the test suite gives failures or errors, your transport is not intgrated
correctly in the default component or you made something wrong during
generation. Retry.

If everything woks, add your new test suite to the overall test suite of the
component, run the whole test suite and verify that everything works as
expected again and commit your changes / send a patch, including all changes
and new files.

Other important clients
=======================

- WebDAVFS/1.*
- XML Spy
- Dreamweaver-WebDAV-SCM1

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