qa:runtests:documentation

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
qa:runtests:documentation [2009/09/01 19:49]
zoe
qa:runtests:documentation [2017/09/22 13:28] (current)
Line 76: Line 76:
 Each test case is executed in it's own process. Many classes are associated with the execution of a single test case. The following subsections give a brief description of the responsibilities of each class. Each test case is executed in it's own process. Many classes are associated with the execution of a single test case. The following subsections give a brief description of the responsibilities of each class.
  
 +===== Run configuration =====
 +This group of classes is responsible for setting the configuration for the whole test run. So, for example the name of the name of the PHP executable under test is set in this group as is the name of the PHP CGI exectuable.
  
-====== Configuration classes ======+===== Test case configuration ===== 
 +Some settings are specific to each test case and need to be set for a single test. These classes are responsible for settings at the level of individual tests.
  
 +====== Run configuration classes ======
 +
 +This sections contains a brief description of each class involved in setting the configuration for the whole test run.
  
 ==== rtRunTestsConfiguration ==== ==== rtRunTestsConfiguration ====
Line 108: Line 114:
 Parent class for classes that set run configuration settings. See 'setting' directory for sub-classes. Note that run settings can be derived from eith command line options or Environment variables, the functions of teh settings classes is mainly to determine which of these has been used and to set the run configuration accordingly. Parent class for classes that set run configuration settings. See 'setting' directory for sub-classes. Note that run settings can be derived from eith command line options or Environment variables, the functions of teh settings classes is mainly to determine which of these has been used and to set the run configuration accordingly.
  
 +===== Test case classes =====
 +====rtPhpTestFile====
 +Reads the contents of a test file, checks that it's a valid test (see precondtions) and removes windows-style line endings.
 +rtPhpTest
 +The main test case class. Takes the contents of the file read by rtPhpTestFile and creates section objects for each section (see Test Case Sections). The run() method runs any executable sections and then compares teh test out put with the expected output. 
 +
 +====rtTestPreCondtion====
 +There are a number of preconditions that must be met before a test can be run. This is the parent class for preconditions. Preconditions are checked as the test file is read (see section on test precondtions)
 +====rtTestConfiguration ====
 +The run configuration can be modified by test case sections. The test configuration class implements the modifications and is used by rtFileSection when running the test.
 +====rtPhpRunner ====
 +As the name suggests, this runs PHP code. It's an almost exact copy of the original run-tests code (system_with_timeout()). No reason to change something that works fine as it is.
 +==== rtPhpTestResults ====
 +Collates the results of running (or attempting to run) a test. If the test has failed ensures that the difference between the expected and actual output is calculated and saved. Decides which files to keep and which to delete. Keeps a record of any saved files and of teh overall status (pass, fail, skip etc) of the test.
 +
 +==== rtTestDifference ====
 +Exact copy of the differencing code in the original run-tests. This code is complex, it might be possible to do better but for now it seems best not to try and modify it.
 +
 +==== rtOutputWriter ====
 +Takes the list of test results and writes in the desired format. Is a parent class for various different formats out output class. Currently only the 'list' format is implemented.
 +
 +
 +
 +====Test Section Classes ====
 +
 +Each test is made up from a number of sections, for example, 
 +--TEST--
 +a title
 +--FILE--
 +<?php
 + some php code
 +?>
 +--EXPECT--
 +the expected result of running the PHP code. 
 +
 +All sections have a name and some contents. Sometimes the contents just have information - for example the test title, sometimes the contents are executable, or used to compare against the output.
 +
 +The base class for all sections is rtSection. This class has a method which initialises the contents to an array of strings.
 +
 +There are four subclasses which extend rtSection, these are rtInformationSection, rtExecutableSection, rtoutputSection and rtConfigurationSection. Each of these are extended again by classes which represent specific sections. The class hierarchy is shown in the attached ODP charts. 
 +
 +A brief description of the responsibilities of each class is given below.
 +
 +====Information Sections====
 +===rtTestSection ===
 +This class just contains the test case title.
 +
 +===rtCreditsSection ===
 +This class contains information about who wrote the test
 +
 +===rtXfailSection===
 +The presence of this section in the test indicates that the test is expected to fail. The contents contain information about the reason for an expected failure.
 +
 +====Executable Sections====
 +
 +===rtFileSection===
 +This is the most complex of the sections. The contents represent the PHP code that needs to be run. The section is responsible for assembling the command line that will run the code. The format of the command line is:
 +
 +php_executable    php_arguments    test.php   test_arguments
 +
 +Note that both php_arguments aand test_arguments can be modified by other test sections and are therefore supplied from a TestConfiguration object and not from the RunConfiguration.
 +The executable code is supplied in a file called test.php, where 'test' is the name of the testcase. The file is constructed fron teh test case contents and written by this section.
 +===rtSkipIfSection===
 +Executes code to determine if the test should be run or not. For example:
 +<?php 
 +if( substr(PHP_OS, 0, 3) == 'WIN') { 
 +  die('skip Not for Windows'); 
 +Note that the first word in the comment is always 'skip' or 'warn'. For example in ext/standard/tests/time/001.phpt:
 +
 +<?php 
 +        if (!function_exists('microtime'))  
 + die('skip microtime() not available'); 
 +        die('warn system dependent'); 
 +?> 
 +Note: the warning is a pretty strange thing to do as part of a section called SKIPIF. I've implemented it here for compatibility but it would be better to have a separate WARN section
 +
 +
 +
 +===rtCleanSection===
 +This section runs code that should clean up after a test. Many people forget that this is a separate piece of executable code - therefore you can't define $myFile in the body of the test and expect to be able to unling $myFile in the CLEAN section. There are currently 71 tests that need to be fixed because the CLEAN sections are a mess.
 +
 +The old run-tests code just chucks away any results from running a CLAEN section. In this code if the results of running the clean section are not an empty string then the results are printed out with a WARN flag.
 +====OutputSections====
 +These sections deal with the expected output of the test and compare it with the actual output.
 +rtExpectSection
 +
 +rtExpectFSection
 +
 +rtExectRegexSection
 +
 +====Configuration sections====
 +These sections have additional configuration information that changes the way that a  single test is run
 +===rtArgsSection===
 +This section contains command line arguments for the test case.  For an example of the usage see
 +ext/standard/tests/general_functions/getopt.phpt
 +
 +Test test_arguments are appended after the testcase as a string preceeded by '--'
 +
 +php_executable    php_arguments    test.php    test_arguments
 +===rtEnvSection===
 +This section adds any environmental variables that are required by a single testcase. For an example of usage see:
 +ext/standard/tests/general_functions/parse_ini_basic.phpt 
 +The environmental variables specified in the test case are appended to the array  of environment variables which is constructed in the run configuration and set in teh testsConfiguration
 +===rtIniSection===
 +This section adds additional commanline arguments to the PHP command line:
 +php_executable    php_arguments    test.php    test_arguments
 +
 +These are added in the form of -d flags and are appended to those already set in the runConfiguration
  
 ====== Parallel Execution ====== ====== Parallel Execution ======
qa/runtests/documentation.1251834584.txt.gz · Last modified: 2017/09/22 13:28 (external edit)