.. include:: /Includes.rst.txt .. index:: ! Testing; Acceptance .. _testing-writing-acceptance: ======================== Writing acceptance tests ======================== Introduction ============ Acceptance testing in TYPO3 world is about piloting a browser to click through a frontend generated by TYPO3 or clicking through scenarios in the TYPO3 backend. The setup provided by `typo3/testing-framework `_ and supported by :file:`runTests.sh` and :file:`docker-compose.yml` as outlined in the :ref:`styleguide example ` is based on `codeception `_ and `selenium `_, usually using chrome as browser. Similar to functional testing, acceptance tests set up an isolated TYPO3 instance that contains everything needed for the scenario. In contrast to functional tests, though, one test suite that contains multiple tests relies on a single instance: With functional tests, each test case gets its own instance, with acceptance tests, there is typically one test suite with only one instance and all tests are executed in this instance. As a result, tests may have dependencies between each other. If for instance one acceptance test created a scheduler tasks, and a second one verifies this task can be deleted again, the second task depends on the first one to be successful. Other than that, the basic instance setup is similar to functional tests: Extensions can be loaded, the instance can be populated with fixture files and database rows and so on. Again, `typo3/testing-framework` helps with managing the instance and contains some helper classes to solve various needs in a typical TYPO3 backend, it for instance helps with selecting a specific page in the page tree. Set up ====== Extension developers who want to add acceptance tests for their extensions should have a look at the :ref:`styleguide example ` for the basic setup. It contains a :file:`codeception.yml` file, a suite, a tester and a bootstrap extension that sets up the system. The bootstrap extension should be fine tuned to specify - similar to functional tests - which specific extensions are loaded and which database fixtures should be applied. Preparation of the browser instance and calling codeception to execute the tests is again performed by :file:`runTests.sh` in docker containers. The chapter :ref:`Extension testing ` is about executing tests and setting up the runtime, while this chapter is about the TYPO3 specific acceptance test helpers provided by the `typo3/testing-framework`. Backend login ============= The suite file (for instance :file:`Backend.suite.yml`) should contain a line to load and configure the backend login module: .. code-block:: yaml :caption: EXT:some_extension/Tests/Acceptance/Backend.suite.yml modules: enabled: - \TYPO3\TestingFramework\Core\Acceptance\Helper\Login: sessions: # This sessions must exist in the database fixture to get a logged in state. editor: ff83dfd81e20b34c27d3e97771a4525a admin: 886526ce72b86870739cc41991144ec1 This allows an editor and an admin user to easily log into the TYPO3 backend without further fuzz. An acceptance test can use it like this: .. code-block:: php :caption: EXT:styleguide/Tests/Acceptance/Backend/ModuleCest.php useExistingSession('admin'); } The call :php:`$I->useExistingSession('admin')` logs in an admin user into the TYPO3 backend and lets it call the default view (usually the about module). Frames ====== Dealing with the backend frames can be a bit tricky in acceptance tests. The `typo3/testing-framework` contains a trait to help here: The backend tester should use this trait, which will add two methods. The implementation of these methods takes care the according frames are fully loaded before proceeding with further tests: .. code-block:: php :caption: EXT:styleguide/Tests/Acceptance/Backend/SomeCest.php // Switch to "content frame", eg the "list module" content $I->switchToContentFrame(); // Switch to "main frame", the frame with the main modules and top bar $I->switchToMainFrame(); PageTree ======== An abstract class of `typo3/testing-framework` can be extended and used to open and select specific pages in the page tree. A typical class looks like this: .. code-block:: php :caption: typo3/sysext/core/Tests/Acceptance/Support/Helper/PageTree.php tester = $I; } } This example is taken from the Core extension, other extensions should use their own instance in an own extension based namespace. If this is done, the PageTree support class can be injected into a test: .. code-block:: php :caption: EXT:some_extension/Tests/Acceptance/Backend/SomeCest.php useExistingSession('admin'); $I->click('List'); $pageTree->openPath(['styleguide TCA demo', 'elements basic']); ... } } The example above (adapt to your namespaces!) instructs the PageTree helper to find a page called "styleguide TCA demo" at root level, to extend that part of the tree if not yet done, and then select the second level page called "elements basic". ModalDialog =========== Similar to the PageTree, an abstract class called :php:`AbstractModalDialog` is provided by `typo3/testing-framework` to help dealing with modal "popups" The class can be extended and used in own extensions in a similar way as outlined above for the PageTree helper.