refactored the test suite bootstrapping and cleaned up test class nam…

…espaces
phpcr · Jul 31, 2011 · c482d3a · c482d3a
1 parent be4a5a6
commit c482d3a
Show file tree

Hide file tree

Showing 61 changed files with 643 additions and 677 deletions.
diff --git a/README.md b/README.md
@@ -7,81 +7,63 @@ numbers in the JCR v2.0 specification, JSR 283.
 (available at http://www.day.com/specs/jcr/2.0/index.html)
 
 
-Some of the chapters have not yet been implemented. They have a file named TODO
+Some of the chapters have not yet been implemented. They have a file named ```TODO```
-in the folder.
+in the folder. The tests in all chapters are probably not feature complete, but
-TODO: check existing chapters for completeness and correctness
+steadily increasing. Help is of course welcome.
-Some tests are missing, some are skipped although jackalope implements the feature.
-Write operations are less tested than read operations. Should go through all tests and fix failing ones and implement missing ones.
-For write, check Session::save too and add more complicated chained operations in CombinedManipulationsTest.
-
-TODO: tests should check workspace if it supports that feature and mark tests
-skipped if implemenation does not claim to implement this feature.
-
-TODO: Although generically useable this checkout comes with fixtures and data for the Jackalope API tests.
-clean out the jackalope references and move all jackalope specific stuff (the .jars and so on)
-into the jackalope api-tests folder. These tests should be clean. The only relevant folders are
-tests and fixtures, plus the .sample files, the rest should go out of this.
 
 ## Usage
 
 The phpcr-api-tests is a suite to test compliance for implementations of
 the java content repository specification.
 [https://github.com/phpcr/phpcr](https://github.com/phpcr/phpcr)
 
-You need to provide a couple of files in order to let the tests detect your
+This test suite is independent of an actual implementation. You need to do a
-implementation:
+couple of things to provide proper bootstrapping for your implementation:
-
 
 * Add the api tests as submodule of your project, for example in a folder tests/api
-* Copy phpunit.dist.xml to the parent folder of where you added the submodule,
+* Copy phpunit.dist.xml to ../phpunit.xml and adapt as necessary.
-    rename it to phpunit.xml and adapt as necessary.
+* Implement the bootstrapping (see below)
-* All <php /> vars beginning with "jcr." are copied to the configuration array
-    that is passed to the functions `getPHPCRSession`,
-    `getRepository` and `getFixtureLoader`.
-    TODO: configuration should be handled by bootstrap and not by baseClass
-* Write your own bootstrap file. Have a look at bootstrap.dist.php You
-  have to implement the following methods:
-    ** getPHPCRSession()
-    ** getRepository()
-    ** getSimpleCredentials()
-    ** getFixtureLoader()
-    TODO: make this a class and move logic for configuration into the bootstrap
-* Implement data for all the necessary fixtures. See the "fixtures/" folder for
-  a JCR XML system view export of the fixture data. If your implementation can
-  not import this format, you will need to convert them into a suitable format.
 
-Once this binding is working, run the tests with phpunit. If you use a normal
+### Bootstrapping
-php installation, this is usually along the lines of:
 
-    $ phpunit -c path/to/folder-with-phpunit
+You find a sample bootstrap.dist.php that you can copy to ../bootstrap.php and
+adjust to your implementation. Your bootstrap must ensure that the
+```ImplementationLoader``` class extending the \PHPCR\Test\AbstractLoader
+is available in the environment.
+The ImplementationLoader is used by the \PHPCR\Test\BaseCase to acquire the
+PHPCR instances.
 
-You can run the tests for a specific chapter of the specification with
+See the inc/AbstractLoader.php file to see what the ImplementationLoader has to do.
-phpunit -c path/to/folder-with-phpunit path/to/NN_chaptername
 
+You can pass parameters from phpunit.xml into your bootstrap with the <php><var... syntax.
 
-### Required Fixtures
+### Fixtures loading
 
-The fixture loading passes strings without the file extension so you can roll
+The ImplementationLoader must provide a fixture loader. The fixture names are
-your own fixtures if you want.
+generic, but all names map to .xml files in the fixtures folder. Those files
-The test suite provides default fixtures in the fixtures folder in the JCR
+are in the JCR system view format. This is the format that is used with
-system view export format. It is recommended to use those.
+SessionInterface::import and produced by SessionInterface::exportSystemView
 
+If your implementation can not import that format, you will need to convert
+them into a suitable format.
 
-### Using jackrabbit_importexport for load your own fixtures
+We recommend not to use your phpcr implementation import() implementation to
+load the fixtures but something stripped down.
+If you use the import() implementation but have some error or bug in that
+implementation, you will get confusing errors on tests that should not fail.
 
-TODO: move this into jackalope, its implementation specific. and we should just
-implement the session::importXML method anyways
 
-The class jackrabbit_importexport can be used to import fixtures in xml format.
+## Running the tests
-It relies on jack.jar. The class can be plugged in Symfony2 autoload mechanism
-through autoload.php, which can be used to feed a MapFileClassLoader istance. E.g:
 
-```php
+Once this binding is working, run the tests with phpunit. If you use a normal
-$phpcr_loader = new MapFileClassLoader(
+php installation, this is usually along the lines of:
-  __DIR__.'/../vendor/doctrine-phpcr-odm/lib/vendor/jackalope/api-test/suite/inc/autoload.php'
+
-);
+    $ phpunit -c path/to/folder-with/phpunit.xml
-$phpcr_loader->register();
+
-```
+You can run the tests for a specific chapter of the specification or just a
+single test case by specifying a path
+
+    $ phpunit -c path/to/folder-with/phpunit.xml path/to/suite/tests/NN_chaptername
 
 
 ## Dependencies
@@ -90,34 +72,35 @@ $phpcr_loader->register();
 * PHPUnit in include_path
 
 
-## Implementation
+## Implementation notes
 
-All tests extend from the baseCase, found in inc/baseCase.php
+This test suite is made to work with all implementations of PHPCR. Never write
-The baseCase prepares a couple of fixtures and assertions that can be used by
+tests for implementation specific things in here - use your applications unit
-the tests. Read the comments in that file for details.
+or functional tests for that.
 
-To improve test running speed, tests should load the fixtures in the
+All tests must extend from the PHPCR\Test\BaseCase which provides the static
-setupBeforeClass method.
+member $loader with the ImplementationLoader to load data.
-For the read-only tests, we have just two fixture files that cover all cases.
+The BaseCase offers infrastructure to load fixtures efficiently and has some
-For the write tests, we have one fixture per file with nodes named after the
+additional assertions that can be used by the tests.
-test names, which baseCase::setUp puts into $this->node. This way, each test
+Read the comments in inc/BaseCase.php for details.
-has its own "root" node and does not influence the other tests.
-
-To add or adjust fixtures, you can use jackrabbit and the jack.jar tool to
-import and export data: http://github.com/jackalope/jackrabbit-importexport
-See the readme file of jack for details.
 
+To improve test running speed, fixture are loaded in the setupBeforeClass
+method. If you need specific fixtures, pass the name to the parent class
+setupBeforeClass method, if you do not need fixtures at all, pass false.
 
-## Note on JCR
+For the read-only tests, we have just two fixtures that cover all cases:
+general/base and general/query
 
-It would be nice if we were able to run the relevant parts of the JSR-283
+To only load fixtures once but reliably test write operations, have a fixture
-Technology Compliance Kit (TCK) against php implementations. Note that we would
+per test case class with nodes named after the test names. The BaseCase will
-need to have some glue for things that look different in php than in Java, like
+put that name into $this->node for each test in setUp(). This way, each test
-the whole topic of Value and ValueFactory.
+has its own "root" node and does not influence the other tests.
-[https://jira.liip.ch/browse/JACK-24](https://jira.liip.ch/browse/JACK-24)
 
-Once we manage to do that, we could hopefully also use the performance test suite
+To add or adjust fixtures, please keep them in the PHPCR system view format.
-[https://jira.liip.ch/browse/JACK-23](https://jira.liip.ch/browse/JACK-23)
+If you work on Jackalope, you can use jackrabbit and the jack.jar tool to
+import and export data:
+http://github.com/jackalope/jackrabbit-importexport
+See the readme file of jackrabbit-importexport for details.
 
 
 # Contributors
@@ -127,6 +110,7 @@ Once we manage to do that, we could hopefully also use the performance test suit
 * Tobias Ebnöther <ebi@liip.ch>
 * Roland Schilter <roland.schilter@liip.ch>
 * Uwe Jäger <uwej711@googlemail.com>
+* Johannes Stark <starkj@gmx.de>
 * Lukas Kahwe Smith <lukas@liip.ch>
 * Benjamin Eberlei <kontakt@beberlei.de>
 * Daniel Barsotti <daniel.barsotti@liip.ch>
diff --git a/bin/jack.jar b/bin/jack.jar
diff --git a/bootstrap.dist.php b/bootstrap.dist.php
@@ -1,109 +1,21 @@
 <?php
 
 /**
- * Sample bootstrap file (as used for jr_cr)
+ * Sample bootstrap file
  *
- * This file does some basic stuff that's project specific.
+ * the thing you MUST do is define the constants as expected in the
- * Please copy the file for your project and make sure phpunit.xml includes
+ * 04_Connecting/RepositoryDescriptorsTest.php
- * this file.
  *
- * function getRepository(config) which returns the repository
+ * Otherwise you may use this file to register autoloaders or require files
- * function getPHPCRSession(config) which returns the session
+ * to have your implementation be ready.
  *
- * TODO: move the following to a base file, as they are not implementation specific
+ * Have a look at the Jackalope repository for an example how the tests are
- * function getSimpleCredentials(user, password) which returns simpleCredentials
+ * integrated https://github.com/jackalope/jackalope
- *
- * constants necessary to the JCR 1.0/JSR-170 and JSR-283 specs
- */
-
-// Make sure we have the necessary config
-$necessaryConfigValues = array('jcr.url', 'jcr.user', 'jcr.pass', 'jcr.workspace', 'jcr.transport');
-foreach ($necessaryConfigValues as $val) {
-    if (empty($GLOBALS[$val])) {
-        die('Please set '.$val.' in your phpunit.xml.' . "\n");
-    }
-}
-
-/**
- * autoloader: jackalope-api-tests relies on this autoloader.
- */
-function jackalopeApiTestsAutoload($class) {
-    $incFile = dirname(__FILE__) . '/../lib/' . str_replace("_", DIRECTORY_SEPARATOR, $class).".php";
-    if (@fopen($incFile, "r", TRUE)) {
-        include($incFile);
-        return $incFile;
-    }
-    return FALSE;
-}
-spl_autoload_register('jackalopeApiTestsAutoload');
-
-/**
- * @return string classname of the repository factory
- */
-function getRepositoryFactoryClass()
-{
-    return 'Jackalope\RepositoryFactoryJackrabbit';
-}
-
-/**
- * @return hashmap to be used with the repository factory
- */
-function getRepositoryFactoryParameters($config)
-{
-    return array('jackalope.jackrabbit_uri' => $config['url']);
-}
-
-/**
- * Repository lookup is implementation specific.
- * @param config The configuration where to find the repository
- * @return the repository instance
- */
-function getRepository($config) {
-    if (empty($config['url']) || empty($config['transport'])) {
-        return false;
-    }
-    return jr_cr::lookup($config['url'], $config['transport']);
-}
-
-/**
- * @param user The user name for the credentials
- * @param password The password for the credentials
- * @return the simple credentials instance for this implementation with the specified username/password
  */
-function getSimpleCredentials($user, $password) {
-    return new jr_cr_simplecredentials($user, $password);
-}
 
-/**
+/*
- * Get a session for this implementation.
+ * you need to define the following constants for the repository descriptor test for JCR 1.0/JSR-170 and JSR-283 specs
- * @param config The configuration that is passed to getRepository
- * @param credentials The credentials to log into the repository. If omitted, $config['user'] and $config['pass'] is used with getSimpleCredentials
- * @return A session resulting from logging into the repository found at the $config path
  */
-function getPHPCRSession($config, $credentials = null) {
-    $repository = getRepository($config);
-    if (isset($config['pass']) || isset($credentials)) {
-        if (empty($config['workspace'])) {
-            $config['workspace'] = null;
-        }
-        if (empty($credentials)) {
-            $credentials = getSimpleCredentials($config['user'], $config['pass']);
-        }
-        return $repository->login($credentials, $config['workspace']);
-    } elseif (isset($config['workspace'])) {
-        return $repository->login(null, $config['workspace']);
-    } else {
-        return $repository->login(null, null);
-    }
-}
-
-function getFixtureLoader($config)
-{
-    require_once "importexport.php";
-    return new jackalope_importexport(__DIR__."/fixtures", (isset($config['jackalope_jar']) ? $config['jackalope_jar'] : null));
-}
-
-/** some constants */
 
 define('SPEC_VERSION_DESC', 'jcr.specification.version');
 define('SPEC_NAME_DESC', 'jcr.specification.name');
@@ -120,3 +32,16 @@ function getFixtureLoader($config)
 define('OPTION_QUERY_SQL_SUPPORTED', 'option.query.sql.supported');
 define('QUERY_XPATH_POS_INDEX', 'query.xpath.pos.index');
 define('QUERY_XPATH_DOC_ORDER', 'query.xpath.doc.order');
+
+/*
+ * you can do things here like registering your autoloader
+ * or require files with classes that are used but not autoloaded
+ */
+require __DIR__.'/../src/Jackalope/autoloader.php';
+
+### Load two classes needed for jackalope unit tests ###
+require __DIR__.'/../tests/Jackalope/TestCase.php';
+require __DIR__.'/../tests/Jackalope/Transport/DoctrineDBAL/DoctrineDBALTestCase.php';
+
+### Load the implementation loader class ###
+require 'ImplementationLoader.php';