Webdav/tests/docs/client_tests.txt - zetacomponents - Git at Google

 ===================
 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
	===================
	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