From d1b2130691e9bdc45fece34d95f048cb39097996 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rapha=C3=ABl=20Emourgeon?= Date: Thu, 10 Sep 2015 22:00:47 +0200 Subject: [PATCH 01/28] Introduce doc to translate... --- Documentation/Fr/Index.xyl | 720 +++++++++++++++++++++++++++++++++++++ 1 file changed, 720 insertions(+) create mode 100644 Documentation/Fr/Index.xyl diff --git a/Documentation/Fr/Index.xyl b/Documentation/Fr/Index.xyl new file mode 100644 index 0000000..aad5412 --- /dev/null +++ b/Documentation/Fr/Index.xyl @@ -0,0 +1,720 @@ + + + +

Ensuring software quality is not easy. The + Hoa\Test library provides several tools to write and to execute + tests, to generate test data or tests themselves etc. This is the basis to + test all Hoa's libraries. Research papers have been published and + implemented inside Hoa\Test and related libraries (like + Hoa\Praspel, Hoa\Realdom etc.).

+ +

Table of contents

+ + + +

Introduction

+ +

Software quality is a vast topic in Computer Science. There is a lot of + strategies, a lot of metrics… and a lot of confusion. One way to ensure + quality in Hoa is based on the testing strategy. Let's introduce this + chapter by some definitions and by presenting the tools provided by the + Hoa\Test library.

+ +

Nature of tests

+ +

Informally, a test is executed on a System Under Test, + abbreviated SUT, and is composed of two parts:

+
    +
  1. Test data to execute the SUT, and
    2. +
  2. An oracle, establishing the test + verdict: Are the result of the execution and the state of + the SUT after its execution the ones we expect or not?
    3. +
+

The values of the verdict are: Success, + fail or inconclusive. A success means this + is what we expect, a fail means this is not what we expect and an + inconclusive means this is not possible to give an answer. The important + part is: “what we expect”. By extension, we understand a + test does not check the SUT is verified.

+
Testing shows the presence, not the absence of + bugs.
+

A test only checks the SUT is valid. The difference is + that a valid system has no bug for some non exhaustive + executions, but a verified system does what it is designed to do. + Despite tests do not proof the absence of bugs, they are useful (easy to + write, easy to read, not all system can be proven etc.). Nevertheless, + depending of the chosen test data, tests can be close to proofs. As an + example, a test with exhaustive test data can be considered as a proof.

+

A test can be written manually, for instance by a test + engineer. A SUT is provided, the engineer uses test data to execute it and + the test verdict is established by the engineer itself. In the case of an + automated test, the execution of the SUT and the test + verdict are computed by the machine. This is the role of the “xUnit” + frameworks, such as atoum or + PHPUnit. The engineer will use the frameworks + to write tests and the machine will execute them. Finally, + automatic tests are generated and executed by the machine. + The machine may rely on a specification, like a contract, to automatically + generate the tests (please, see the + Hoa\Praspel library or the research papers bellow we have + published about it to learn more about the Design-by-Contract and + Contract-based Testing paradigms). Automatic tests have two sub-categories: + Online and offline tests. Online means the + tests are generated and executed in one-pass, while offline means the tests + are executed and then executed later (with the test data or not).

+

In Hoa, we have both automated and offline + automatic tests.

+

This is a high classification of tests. A thinner one is described by the + following schema explaining what kind of tests to write:

+
+ +
Dimensions of the test universe is represented by + 3 axis.
+
+

The “Conception support” axis describes the visibility we + have on the System Under Test: Either black box or + white box. Their meanings are different according to the + context but we can consider a system as a white box if we look and use what + is inside the box, else this is a black box. For instance, + for unit tests, let say with a function as the SUT, black box testing will + consider only the inputs and the outputs of the function without considering + its body (even if it reads or writes global variables, streams etc.). On the + other hand, white box testing will consider the body of the function and the + testing strategy will be totally different. What we expect from a black box + or a white box system is not the same.

+

The “System size" axis describes at what level (or + altitude) do we test: From the lowest one, unit (a function + or a method) to the highest one, the whole system, which + includes components (a set of functions) and the + integration of these components inside other ones, which + together form the system. All levels are important: This is not because a + function does what it is supposed to do that it will integrate nicely with + another one.

+

Finally, the “Type of test” axis describes the goal of the + tests: Either functional (“everything works as expected and + that's it”), robustness (“this is not possible to put the + system into an error state if we do something unexpected”), + performance (“the system supports heavy loads and behaves + as expected under these conditions”) etc.

+

In Hoa, we have white box and black box, + unit and functional tests. We also include + performance tests in some libraries.

+

Remember that each point in this test universe may imply different tools + and different development practices. When talking about tests, this is + important to have this schema in minds and to wonder where our problematic + locates.

+ +

Test, test case and test + suite

+ +

Formally, a test of a SUT is a set of data (called test + data) that fixes the values of the arguments (also called inputs) of the + SUT. A test case is a pair composed of a state (the context + in which the test is executed) and a test. A test suite is + a set of test cases. Therefore, there is two states from the test point of + view: A pre-state —before the execution of the SUT— and a + post-state —after the execution—.

+

Building the pre-state is something crucial: The goal is to put the SUT into a + specific (pre-)state in order to test it. The part of the test case + responsible to create the pre-state is called the preamble. + Thus, the preambler is a code that puts the SUT into a specific state.

+

So, when writing a test case, we will have 3 items to consider:

+
    +
  1. The preamble, to put the SUT into a specific + state,
    2. +
  2. The execution, to run the SUT and get a result,
    3. +
  3. The oracle, to compute the test verdict (based on the + execution result and the post-state).
    4. +
+

The oracle consists of a sequence of assertions: “Is this value equals + to…?”, “Is this value changed this way…?” etc. It is supposed to be able to + check the form of some data as much as comparing other data between the + pre-state and the post-state.

+

In a test case, we represent and introduce the preamble, the execution and + the oracle respectively by the given, when and + then keywords. This will be detail hereinafter.

+ +

Test framework

+ +

Hoa did not developed its own test framework for several reasons. The main + one is that this is a laborious task. It implies more development, more tools + to maintain, less people focused on Hoa etc. Instead, we prefer to choose a + good project to rely on and contribute to it. Then, we choose + atoum, “a simple, modern and intuitive test + framework”.

+

Thus, Hoa\Test is the basis to test all Hoa's libraries. It + wraps atoum and it aims at being a bridge between Hoa's features and + atoum's features. It also adds some features when needed. This is more than + an abstract layer on top of atoum. Hoa\Test also provides its + own command-line to run the tests with everything pre-packaged. Consequently, + Hoa\Test provides a ready-to-use test environment targeting + Hoa.

+

One shall not be surprised to see some contributors of Hoa as contributors + of atoum. The two communities are strongly linked. Hoa also provides + official contributions to atoum like + the + atoum/praspel-extension extension and some other + extensions are based on Hoa, like + the + atoum/ruler-extension extension which is based on + the Hoa\Ruler library, also + used by Hoa\Test. Even some atoum's extensions are tested with + atoum and Hoa (with atoum/praspel-extension). The loop is + complete.

+ +

Research papers

+ +

Several research papers (articles, journal and a PhD + thesis) have been published about Hoa\Test, + Hoa\Praspel and Hoa\Realdom:

+ +

These papers are about test data generation and + validation, including Design-by-Contract and Contract-based + Testing in PHP, along with Grammar-based Testing and Solver-based Testing.

+ +

Writing tests

+ +

Each library provides a Test/ directory at the root of the + repository. This is where tests are located. Automated unit tests can be found in + the Test/Unit/ directory while automatically generated unit tests can + be found in the Test/Praspel/Unit/ directory (not by default, + they must be generated first).

+ +

Automated unit tests

+ +

In Hoa, a test suite is represented by a file, containing a class. A test + case is a method in this class, expressing the preamble, the execution of + the SUT and the oracle. The template of a test suite is then the following + (let's say for the Test/Unit/Bar.php test suite of the + Hoa\Foo library):

+ 
namespace Hoa\Foo\Test\Unit;
+
+use Hoa\Foo\Bar as SUT;
+use Hoa\Test;
+
+class Bar extends Test\Unit\Suite
+{
+    public function case_classic()
+    {
+        // test case.
+    }
+}
+

We define an alias SUT to the current System Under Test. In a + unit test context, this is a method or a class. We can also declare the + CUT alias, standing for Class Under Test, and LUT + for Library Under Test. LUT is useful if we need to access to + other classes in the same library. Because they are unit tests, we should not + use other classes but remember that a test case is composed of a preamble and + it needs to be build. In this case, LUT could be defined to + Hoa\Foo.

+

The Bar class extends the Hoa\Test\Unit\Suite + class, which defines a unit test suite. It offers all the test API we need + to write tests.

+

Test cases are public method. They do not use a camel case notation but an + underscore lower-cased notation. They must be prefixed by + case_. The template of a test case must follow the preamble, + execution and oracle principle, respectively represented by the + given, when and then keywords, and + thus must be written as follows:

+ 
public function case_classic()
+{
+    $this
+        ->given(
+            …,
+            …,
+            …
+        )
+        ->when(
+            …,
+            $result = …
+        )
+        ->then
+            ->…;
+}
+

The given and when “control flow structures” are + function calls with an unbounded arity. They are void methods, they do + nothing. The goal is not to pass something to them but to declare variables, + to establish the preamble and to execute the test. For instance:

+ 
public function case_sum()
+{
+    $this
+        ->given(
+            $x = 1,
+            $y = 2
+        )
+        ->when(
+            $result = $x + $y
+        )
+        ->then
+            ->integer($result)
+                ->isEqualTo(3);
+}
+

This is strictly equivalent to write:

+ 
public function case_sum()
+{
+    // Given:
+    $x = 1;
+    $y = 2;
+    // When:
+    $result = $x + $y;
+    // Then:
+    $this->integer($result)>-isEqualTo(3);
+}
+

We however use the first form, which is clearer: Indentation, special + keywords (through method names) and force us to clearly separate these + 3 parts: Preamble, test execution and oracle.

+

The $result variable is special. It must + always hold the result of the test execution, i.e. the + result of the SUT's return statement. This + is a convention.

+

One test case can contain multiple test executions with multiple oracles + (for instance if a SUT returns different results according to the time). + Then, the test case must be written as follows:

+ 
public function case_classic()
+{
+    $this
+        ->given(…)
+        ->when($result = …)
+        ->then
+            ->…
+
+        ->when($result = …)
+        ->then
+            ->…
+
+        ->when($result = …)
+        ->then
+            ->…;
+}
+

Assertions are always used after the then part and most of the + time has the form assertion-group->assertion. + We can link assertion groups too. For instance:

+ 
public function case_sum()
+{
+    $this
+        ->given(
+            $x = 1,
+            $y = 2
+        )
+        ->when(
+            $result = $x + $y
+        )
+        ->then
+            ->integer($result)
+                ->isLowerThan(4)
+                ->isGreaterThan(2)
+            ->string((string) $result)
+                ->isNotEmpty();
+}
+

The list of all + assertions can be find on atoum's documentation. Even if this is pretty + natural to write assertions because it is close to “human conventions”, + sometimes this is useful to discover that a specific assertion already exists, + like float->isNearlyEqualTo which compares two floats as + expected most of the time. So feel free to check atoum's documentation + often!

+ +

Automatic test data + generation

+ +

Hoa\Test includes + the + atoum/praspel-extension extension. This extension + includes the Hoa\Praspel + library and the + Hoa\Realdom library inside atoum. When doing manual or + automated tests, this extension can be used to automatically generate + test data.

+

All we need is to describe a realistic domain (see + the Hoa\Realdom library) with + the realdom assertion group and then use the sample + “assertion” (internally this is a handler but the syntax is the same) + to generate one value or sampleMany to generate many values. For + instance, to automatically generate an integer in the interval 7 to 13 or 42 + to 153:

+ 
public function case_sum()
+{
+    $this
+        ->given(
+            $_x =
+                $this
+                    ->realdom
+                        ->boundinteger(7, 13)
+                        ->or
+                        ->boundinteger(42, 153),
+            $x = $this->sample($_x)
+        )
+        ->when(…)
+        ->then
+          ->…;
+}
+

Actually, atoum/praspel-extension provides 3 asserters to + generate data and 1 asserter to validate data:

+
    +
  1. realdom to create a a realistic domain disjunction (see the + or in the previous example),
    2. +
  2. sample to generate one datum from a realistic domains + disjunction,
    3. +
  3. sampleMany to generate several data,
    4. +
  4. predicate to validate a datum against a realistic domain + disjunction.
    5. +
+

Hoa\Realdom provides a standard realistic domain collection, + which includes very useful ones, like regex that describes a + regular expression (in the PCRE format). + Thus, we are able to automatically generate a datum against + or validate data matching regular + expressions. The following example generate one string similar to + an email address:

+ 
$this
+    ->given(
+        $email = $this->sample(
+            $this->realdom->regex('/[\w\-_]+(\.[\w\-\_]+)*@\w\.(net|org)/')
+        ),
+        …
+    )
+    ->…
+

The following example declare a realistic domain representing a date with + the d/m H:i format, between yesterday and the next Monday:

+ 
$this
+    ->given(
+        $_date = $this->realdom->date(
+            'd/m H:i',
+            $this->realdom->boundinteger(
+                $this->realdom->timestamp('yesterday'),
+                $this->realdom->timestamp('next Monday')
+            )
+        )
+    )
+    ->…
+

Then, to generate one date:

+ 
$this->sample($_date)
+

Or to sample 42 dates:

+ 
$this->sampleMany($_date, 42)
+

Similarly, booleans, arrays, classes, colors, strings based on grammars + etc. can be generated… but also validated! The predicate + asserter is a real one, contrary to realdom, sample + and sampleMany. By nature, it computes a boolean: Either + true or + false. It can be used on a realistic domain + disjunction, for instance:

+ 
$this
+    ->given(
+        $_date = $this->realdom->date(
+            'd/m H:i',
+            $this->realdom->boundinteger(
+                $this->realdom->timestamp('yesterday'),
+                $this->realdom->timestamp('next Monday')
+            )
+        ),
+        $stuff = …
+    )
+    ->when($result = SUT::compute($stuff)
+    ->then
+        ->predicate($_date, $result);
+

In the above example, the _date realistic domain is described, + not to generate a datum but to validate the result from the SUT.

+

To get more information about Grammar-based Testing, please, see + the Hoa\Compiler library. + To get more information about Solver-based Testing, please, see the + the Hoa\Realdom library. In + all cases, please, see our research papers.

+ +

Automatically generated + tests

+ +

This section has been addressed by a PhD thesis and several + research papers. However, tools are not + stable yet and documentation is under-writing. Please, refer to + the Hoa\Praspel library to + get more information.

+ +

Run tests

+ +

Most of the time, we will run tests from inside a library repository. + Composer will be required to install + dependencies of the library, which includes Hoa\Test as a + development dependency. Thus, from the root of the library repository:

+ 
$ composer install
+

By default it will install development dependencies. If not, force it by + adding the --dev option.

+

A vendor/ directory is then created. Inside this directory, we + will find the bin/hoa command (please, see + the Hoa\Cli library). Executing + this command without any option will list all available sub-commands for this + current installation. We should see the test commands. To execute tests, we + will use the test:run sub-command. We must provide the directory + where tests are stored, which is always Test/. Thus:

+ 
$ vendor/bin/hoa test:run --directories Test/
+

Note that the --directories option has a plural form. This is + because we can specify more than one directory name by using a comma.

+

At this point, we will see test executing themselves.

+ +

Interpreting the test + result

+ +

The CLI test reporter will use colours to indicate the test + verdict: green for success, red for fail or inconclusive. In case + of a success, we should see:

+ 
Success (S tests, c/C methods, V void method, K skipped method, A assertions)!
+

where:

+
    +
  • S is the number of test suites,
    • +
  • c and C are the numbers of + test cases,
    • +
  • V is the number of inconclusive test cases,
    • +
  • K is the number of skipped test cases,
    • +
  • A is the numbre of assertions.
    • +
+

In case of a failure, we should see:

+ 
Failure (S tests, c/C methods, V void method, K skipped method, …, F failure, E error, X exception)!
+> There is F failure:
+…
+
    +
  • F is the number of failed test cases,
    • +
  • E is the number of unexpected errors,
    • +
  • X is the number of unexpected exceptions.
    • +
+

For each failure description, a “diff” will be computed, i.e. a textual + differential representation of what we expect and what we got.

+ +

Debugging mode

+ +

In some cases it is possible that debugging information are accessible but + hidden for a regular running. To enable the outputs, we need to use the + --debug option; thus:

+ 
$ vendor/bin/hoa test:run --directories Test/ --debug
+

The order of the option does not matter, as usual with the hoa + command.

+

To produce a debugging information, we should use the dump + handler while writing the test case. For instance:

+ 
public function case_sum()
+{
+    $this
+        ->given(
+            $x = 1,
+            $y = 2
+        )
+        ->when(
+            $result = $x + $y
+        )
+        ->then
+            ->dump($result)
+            ->integer($result)
+                ->isEqualTo(3);
+}
+ +

Select tests to run

+ +

Selecting tests to run enables a faster feedback and a + shorter “test loop”. We previously saw the + --directories option to pick some directories: Either the test + root directory Test/ or one or many sub-directories (with + --directories Test/Foo/,Test/Bar/,Test/Baz/Qux/ for + instance).

+

We also have the --files option to select one or many + specific files to run. For instance:

+ 
$ vendor/bin/hoa test:run --files Test/Unit/Foo.php,Test/Unit/Bar.php
+

Finally, Hoa\Test requires + the + atoum/ruler-extension extension to be installed. This + extension allows to precisely filter tests to run. We + access to it with the --filter option followed by an + expression. Fun fact: Expressions are based on + the Hoa\Ruler library!

+

The following variables are available in a filter expression:

+
    +
  • method represents the test case name,
    • +
  • class represents the test suite name,
    • +
  • namespace represents the test suite namespace,
    • +
  • tags represents test suite or test case's tags.
    • +
+

All standard operators from the Hoa\Ruler library can be used. + So for instance, to only run the Hoa\Foo\Test\Unit\Bar test + suite, which is represented by a class, we will write:

+ 
$ vendor/bin/hoa test:run --directories Test/ --filter 'class = "Hoa\Foo\Test\Unit\Bar"'
+

Or, to run only two specific test cases, let's say + case_sum and case_baz:

+ 
$ vendor/bin/hoa test:run --directories Test/ --filter 'method = "case_sum" or method = "case_baz"'
+

The previous example is strictly equivalent to:

+ 
$ vendor/bin/hoa test:run --directories Test/ --filter 'method in ["case_sum", "case_baz"]'
+

Another example to filter by test suites' name: Only the ones that end by + Qux:

+ 
$ vendor/bin/hoa test:run --directories Test/ --filter 'class matches "Qux$"'
+

The matches operator requires a regular expression to + the PCRE format.

+

Finally, test suites and test cases can hold one or more tags, thanks to the + @tags annotation. An annotation is a comment of kind /** + … */ located on top of a class, interface, method, + function etc. Tags allow to have a transversal classification of test cases. + For instance:

+ 
/**
+ * @tags featureA featureB
+ */
+public function case_sum()
+{
+    // …
+}
+

To run only test cases with the tag featureA, we will use the + following command-line:

+ 
$ vendor/bin/hoa test:run --directories Test/ --filter '"featureA" in tags'
+

Here, the variable tags contains an array of strings, + representing tag names.

+ +

Choose the PHP virtual + machine

+ +

When testing, this is also useful to be able to select one specific + PHP virtual machine, like a + specific version of PHP (the default virtual machine) or + the latest version of HHVM for instance. There + is several PHP virtual machines nowadays and we cannot ignore them.

+

We select a virtual machine by using the + --php-binary option and by providing a path to the virtual CLI + binary; thus, for instance:

+ 
$ vendor/bin/hoa test:run --directories … --php-binary /usr/bin/php
+

We can imagine the --php-binary option value defined by a + global variable. Thus, we could re-use the same script to execute tests + against several PHP virtual machines, like:

+ 
$ PHP_BIN=/usr/bin/php vendor/bin/hoa test:run --directories … --php-binary $PHP_BIN
+

Please, remember to use PHP syntax and features described in + the PHP specification as + most as possible.

+ +

Test execution engine

+ +

atoum provides several test execution engines, such as:

+
    +
  • Inline, one test case after another in the same + process,
    • +
  • Isolate, one test case after another but each time in a + new process,
    • +
  • Concurrent, “all” test cases at the same time in + separated processes.
    • +
+

When running tests, isolation is really important: No memory conflict, no + execution conflict, state of the System Under Test is reset each time etc. + The test verdict does not depend of a previous run and is therefore + deterministic and unambiguous (also if the + SUT is).

+

By default, Hoa\Test will use the concurrent + test execution engine. All test cases are not executed at the same time; in + fact the number of test cases to run is defined by the number of processes to + use. By default, this is either 2 or 4 depending of the platform but we can + specify it by using the --concurrent-processes option. Thus, to + force using 1024 processes to run tests (assuming we have a monster + computer):

+ 
$ vendor/bin/hoa test:run --directories Test/ --concurrent-processes 1024
+

Because the inline test execution engine is not interesting for Hoa's + usecases and contexts and because the isolate test execution engine has more + cons than pros compared to the concurrent one (mainly the latter is faster + than the former), we cannot change the test execution engine. However, to + emulate the isolate test engine, we could force + --concurrent-processes to 1.

+ +

Virtual file system

+ +

The Hoa\Test library provides a virtual file system over its + hoa:// protocol to ease testing of files or directories.

+

The root of the virtual file system is + hoa://Test/Vfs/. Everything added after this root will be a path + to a virtual file or a directory. + Additional query strings can be present to specify more + information, such as permissions, access time etc. The parent-child relation + is automatically created, not need to specify that a file is a child of a + directory, this is deduced from the path.

+

Note: The virtual file system is only accessible from inside a test + case.

+ +

Files or directories

+ +

A virtual file Foo can be represented by the following path: + hoa://Test/Vfs/Foo. In this case, either we open it with + regular stream functions like + fopen, + fread, + fwrite, + file_put_content + etc. or, with the Hoa\File + library, thus:

+ 
$file = new Hoa\File\ReadWrite('hoa://Test/Vfs/Foo');
+$file->writeAll('Hello world!');
+
+var_dump($file->readAll());
+
+/**
+ * Will output:
+ *     string(12) "Hello world!"
+ */
+

To create a directory, we must specify a stream type by using the + type query string; thus:

+ 
$directory = new Hoa\File\Directory('hoa://Test/Vfs/Foo?type=directory');
+

This is due to the fact that we cannot deduce stream type based on its + name. By default, type=file is implied.

+

For the rest, it works like any regular files or directories, nothing + different.

+ +

Permissions

+ +

To change the permissions, either the specific stream permission functions + can be used or we can set them directly by using the + permissions query string followed by an octal value; thus:

+ 
$file = new Hoa\File\ReadWrite('hoa://Test/Vfs/Foo?permissions=0644');
+var_dump($file->getReadablePermissions());
+
+/**
+ * Will output:
+ *     string(10) "-rw-r--r--"
+ */
+

As any query strings, we can concatenate key-values by using the + & symbol. For instance, + type=directory&permissions=0644 represents a directory + with the 0644 permissions.

+ +

Access-, change- and + modify-time

+ +

This can also be useful to define access-, change- and modify-time by + respectively using the atime, ctime and + mtime query strings. The expected values are an integer + representing a timestamp (a number of seconds). Thus, to represent a file + that has been accessed in the future (in 1 minute):

+
$aTime = time() + 60;
+$file  = new Hoa\File\ReadWrite('hoa://Test/Vfs/Foo?atime=' . $aTime);
+ +

Conclusion

+ +

The Hoa\Test library is a set of tools to make white + box or black box, unit or + functional, automated and + automatic unit tests. This is more than a wrapper around + atoum: It provides a test structure and + conventions, a virtual file system and + extensions to automatically generate test + data, automatically generate tests or to get a powerful test + filtering system. Grammar-based Testing, Solver-based + Testing, Random-based Testing, Contract-based Testing… all these paradigms + live in Hoa\Test. Several research + papers have been published in major test literature and conferences.

+ + + From c53931e0a6fee90cfa7068d4760478a5d3a87800 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rapha=C3=ABl=20Emourgeon?= Date: Thu, 10 Sep 2015 22:17:07 +0200 Subject: [PATCH 02/28] Translate intro. --- Documentation/Fr/Index.xyl | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/Documentation/Fr/Index.xyl b/Documentation/Fr/Index.xyl index aad5412..67b8396 100644 --- a/Documentation/Fr/Index.xyl +++ b/Documentation/Fr/Index.xyl @@ -1,14 +1,15 @@ -

Ensuring software quality is not easy. The - Hoa\Test library provides several tools to write and to execute - tests, to generate test data or tests themselves etc. This is the basis to - test all Hoa's libraries. Research papers have been published and - implemented inside Hoa\Test and related libraries (like - Hoa\Praspel, Hoa\Realdom etc.).

- -

Table of contents

+

Assurer la qualité du logiciel n'est pas facile. La + bibliothèque Hoa\Test fournit plusieurs outils pour écrire et + exécuter des tests, générer des données de tests ou même des tests eux-même + etc… Ceci est la base pour tester les bibliothèques de Hoa. Des articles de + recherche ont été publiés et implémentés dans Hoa\Test et des + librairies connexes (comme Hoa\Praspel, + Hoa\Realdom etc.)

+ +

Table des matières

From 3bd5bba3ede247deadb18c0932fc1c6823cfb554 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rapha=C3=ABl=20Emourgeon?= Date: Mon, 14 Sep 2015 21:32:50 +0200 Subject: [PATCH 03/28] Continue introduction translation. --- Documentation/Fr/Index.xyl | 56 ++++++++++++++++++++------------------ 1 file changed, 29 insertions(+), 27 deletions(-) diff --git a/Documentation/Fr/Index.xyl b/Documentation/Fr/Index.xyl index 67b8396..159115b 100644 --- a/Documentation/Fr/Index.xyl +++ b/Documentation/Fr/Index.xyl @@ -15,37 +15,39 @@

Introduction

-

Software quality is a vast topic in Computer Science. There is a lot of - strategies, a lot of metrics… and a lot of confusion. One way to ensure - quality in Hoa is based on the testing strategy. Let's introduce this - chapter by some definitions and by presenting the tools provided by the - Hoa\Test library.

+

La qualité du logiciel est un sujet très vaste en Informatique. Il y a + beaucoup de stratégies, beaucoup de mesures… et beaucoup de confusion. Une + façon d'assurer la qualité dans Hoa repose sur la stratégie de test. + Commençons ce chapitre par quelques définitions et une présentation des outils + fournis par la bibliothèque Hoa\Test.

-

Nature of tests

+

Nature des tests

-

Informally, a test is executed on a System Under Test, - abbreviated SUT, and is composed of two parts:

+

Un test est exécuté sur un System Under Test, + abrégé SUT, et est composé de deux parties :

    -
  1. Test data to execute the SUT, and
    2. -
  2. An oracle, establishing the test - verdict: Are the result of the execution and the state of - the SUT after its execution the ones we expect or not?
    3. +
  3. lesdonnées de test pour exécuter le SUT, et
    4. +
  4. un oracle, qui établit le + verdict du test: est-ce que les résultats de l'exécution et + l'état du SUT après son exécution sont ceux que l'on attendait ou pas ?
-

The values of the verdict are: Success, - fail or inconclusive. A success means this - is what we expect, a fail means this is not what we expect and an - inconclusive means this is not possible to give an answer. The important - part is: “what we expect”. By extension, we understand a - test does not check the SUT is verified.

-
Testing shows the presence, not the absence of - bugs.
-

A test only checks the SUT is valid. The difference is - that a valid system has no bug for some non exhaustive - executions, but a verified system does what it is designed to do. - Despite tests do not proof the absence of bugs, they are useful (easy to - write, easy to read, not all system can be proven etc.). Nevertheless, - depending of the chosen test data, tests can be close to proofs. As an - example, a test with exhaustive test data can be considered as a proof.

+

Les valeurs du verdict sont : succès, + échec ou ambigu. Un succès signifie que c'est + ce que nous attendions, un échec signifie que ce n'est pas ce que nous + attendions et ambigu signifie qu'il n'est pas possible de donner une réponse. + La partie importante est “ce que nous attendions”. Par extension, + nous comprenons qu'un test n'asserte pas que le SUT est + vérifié.

+
Les tests montrent la présence, non pas l'absence + de bogues.
+

Un test ne vérifie que la validité du SUT. La différence + est qu'un système valide n'a pas de bug pour quelques exécutions non + exhaustives, tandis qu'un système vérifié fait ce pourquoi il a été + conçu. Bien que les tests ne prouvent pas l'absence de bug, ils sont utiles + (facile à écrire, facile à lire, tout le système ne peut être prouvé etc). + Cependant, en fonction des données de test choisies, les tests peuvent être + presque considérés comme des preuves. Par exemple, un test avec des données de + tests exhaustives peut être considéré comme une preuve.

A test can be written manually, for instance by a test engineer. A SUT is provided, the engineer uses test data to execute it and the test verdict is established by the engineer itself. In the case of an From d5058b9ff786869ba9d4f55b5a50bcb22169c1f5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rapha=C3=ABl=20Emourgeon?= Date: Tue, 15 Sep 2015 23:16:33 +0200 Subject: [PATCH 04/28] Fix many typos. --- Documentation/Fr/Index.xyl | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/Documentation/Fr/Index.xyl b/Documentation/Fr/Index.xyl index 159115b..ee397dc 100644 --- a/Documentation/Fr/Index.xyl +++ b/Documentation/Fr/Index.xyl @@ -4,10 +4,10 @@

Assurer la qualité du logiciel n'est pas facile. La bibliothèque Hoa\Test fournit plusieurs outils pour écrire et exécuter des tests, générer des données de tests ou même des tests eux-même - etc… Ceci est la base pour tester les bibliothèques de Hoa. Des articles de + etc. Ceci est la base pour tester les bibliothèques de Hoa. Des articles de recherche ont été publiés et implémentés dans Hoa\Test et des - librairies connexes (comme Hoa\Praspel, - Hoa\Realdom etc.)

+ bibliothèques connexes (comme Hoa\Praspel, + Hoa\Realdom etc.).

Table des matières

@@ -15,7 +15,7 @@

Introduction

-

La qualité du logiciel est un sujet très vaste en Informatique. Il y a +

La qualité logicielle est un sujet très vaste en Informatique. Il y a beaucoup de stratégies, beaucoup de mesures… et beaucoup de confusion. Une façon d'assurer la qualité dans Hoa repose sur la stratégie de test. Commençons ce chapitre par quelques définitions et une présentation des outils @@ -26,25 +26,25 @@

Un test est exécuté sur un System Under Test, abrégé SUT, et est composé de deux parties :

    -
  1. lesdonnées de test pour exécuter le SUT, et
    2. +
  2. les données de test pour exécuter le SUT ; et
  3. un oracle, qui établit le - verdict du test: est-ce que les résultats de l'exécution et - l'état du SUT après son exécution sont ceux que l'on attendait ou pas ?
    4. + verdict du test : est-ce que les résultats de l'exécution et + l'état du SUT après son exécution sont ceux que nous attendions ou pas ?

Les valeurs du verdict sont : succès, échec ou ambigu. Un succès signifie que c'est ce que nous attendions, un échec signifie que ce n'est pas ce que nous attendions et ambigu signifie qu'il n'est pas possible de donner une réponse. - La partie importante est “ce que nous attendions”. Par extension, - nous comprenons qu'un test n'asserte pas que le SUT est + La partie importante est « ce que nous attendions ». Par + extension, nous comprenons qu'un test n'asserte pas que le SUT est vérifié.

Les tests montrent la présence, non pas l'absence - de bogues.
-

Un test ne vérifie que la validité du SUT. La différence + de bugs. +

Un test n'assure que la validité du SUT. La différence est qu'un système valide n'a pas de bug pour quelques exécutions non exhaustives, tandis qu'un système vérifié fait ce pourquoi il a été conçu. Bien que les tests ne prouvent pas l'absence de bug, ils sont utiles - (facile à écrire, facile à lire, tout le système ne peut être prouvé etc). + (facile à écrire, facile à lire, tous les systèmes ne peuvent être prouvés etc). Cependant, en fonction des données de test choisies, les tests peuvent être presque considérés comme des preuves. Par exemple, un test avec des données de tests exhaustives peut être considéré comme une preuve.

From a0ce582d06864708f47593825e512895d64d99a9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rapha=C3=ABl=20Emourgeon?= Date: Wed, 16 Sep 2015 09:13:39 +0200 Subject: [PATCH 05/28] Translate unconclusive correctly. --- Documentation/Fr/Index.xyl | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Documentation/Fr/Index.xyl b/Documentation/Fr/Index.xyl index ee397dc..b81deaf 100644 --- a/Documentation/Fr/Index.xyl +++ b/Documentation/Fr/Index.xyl @@ -32,9 +32,9 @@ l'état du SUT après son exécution sont ceux que nous attendions ou pas ?

Les valeurs du verdict sont : succès, - échec ou ambigu. Un succès signifie que c'est - ce que nous attendions, un échec signifie que ce n'est pas ce que nous - attendions et ambigu signifie qu'il n'est pas possible de donner une réponse. + échec ou non conclusif. Un succès signifie + que c'est ce que nous attendions, un échec signifie que ce n'est pas ce que nous + attendions et non conclusif signifie qu'il n'est pas possible de donner une réponse. La partie importante est « ce que nous attendions ». Par extension, nous comprenons qu'un test n'asserte pas que le SUT est vérifié.

From e135b2040ff3639dcacfc70eb7b0d020d414a31f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rapha=C3=ABl=20Emourgeon?= Date: Tue, 29 Sep 2015 08:55:45 +0200 Subject: [PATCH 06/28] Continue. --- Documentation/Fr/Index.xyl | 129 +++++++++++++++++++++---------------- 1 file changed, 73 insertions(+), 56 deletions(-) diff --git a/Documentation/Fr/Index.xyl b/Documentation/Fr/Index.xyl index b81deaf..2260cdb 100644 --- a/Documentation/Fr/Index.xyl +++ b/Documentation/Fr/Index.xyl @@ -48,27 +48,31 @@ Cependant, en fonction des données de test choisies, les tests peuvent être presque considérés comme des preuves. Par exemple, un test avec des données de tests exhaustives peut être considéré comme une preuve.

-

A test can be written manually, for instance by a test - engineer. A SUT is provided, the engineer uses test data to execute it and - the test verdict is established by the engineer itself. In the case of an - automated test, the execution of the SUT and the test - verdict are computed by the machine. This is the role of the “xUnit” - frameworks, such as atoum or - PHPUnit. The engineer will use the frameworks - to write tests and the machine will execute them. Finally, - automatic tests are generated and executed by the machine. - The machine may rely on a specification, like a contract, to automatically - generate the tests (please, see the - Hoa\Praspel library or the research papers bellow we have - published about it to learn more about the Design-by-Contract and - Contract-based Testing paradigms). Automatic tests have two sub-categories: - Online and offline tests. Online means the - tests are generated and executed in one-pass, while offline means the tests - are executed and then executed later (with the test data or not).

-

In Hoa, we have both automated and offline - automatic tests.

-

This is a high classification of tests. A thinner one is described by the - following schema explaining what kind of tests to write:

+

Un test peut être écrit manuellement, par exemple par un + ingénieur de test. Un SUT est fourni, l'ingénieur utilise des données de test + pour l'exécuter et le verdict du test est établi par l'ingénieur. Dans le cas + d'un test automatisé, l'exécution du SUT et le verdict du + test sont calculés par la machine. C'est le rôle des frameworks « xUnit » tel + que atoum ou + PHPUnit. L'ingénieur utilisera les frameworks + pour écrire des tests et la machine pour les exécuter. Finalement les tests + automatiques sont générés et exécutés par la machine. + La machine peut compter sur une spécification, comme un contrat, pour générer + automatiquement les tests (s'il vous plaît, allez voir la + bibliothèque Hoa\Praspel ou + les rapports de recherches que nous avons publiés ci-dessous pour en apprendre + plus sur les paragdimes de Design-by-Contract et + Contact-based Testing). + Les tests automatiques ont deux sous-catégories : les tests + en ligne ou hors-ligne. En ligne signifie + que les tests sont générés et exécutés en une seule passe, tandis que + hors-ligne signifie que les tests sont générés et exécutés plus tard + (avec des données de test ou non).

+ +

Dans Hoa nous avons aussi bien des tests automatisés que + des tests hors-ligne automatiques.

+

Ceci est une classification générale des tests. Une plus précise est décrite + par le schéma ci-dessous qui explique quel type de test écrire :

Dimensions of the test universe is represented by 3 axis. -

The “Conception support” axis describes the visibility we - have on the System Under Test: Either black box or - white box. Their meanings are different according to the - context but we can consider a system as a white box if we look and use what - is inside the box, else this is a black box. For instance, - for unit tests, let say with a function as the SUT, black box testing will - consider only the inputs and the outputs of the function without considering - its body (even if it reads or writes global variables, streams etc.). On the - other hand, white box testing will consider the body of the function and the - testing strategy will be totally different. What we expect from a black box - or a white box system is not the same.

-

The “System size" axis describes at what level (or - altitude) do we test: From the lowest one, unit (a function - or a method) to the highest one, the whole system, which - includes components (a set of functions) and the - integration of these components inside other ones, which - together form the system. All levels are important: This is not because a - function does what it is supposed to do that it will integrate nicely with - another one.

-

Finally, the “Type of test” axis describes the goal of the - tests: Either functional (“everything works as expected and - that's it”), robustness (“this is not possible to put the - system into an error state if we do something unexpected”), - performance (“the system supports heavy loads and behaves - as expected under these conditions”) etc.

-

In Hoa, we have white box and black box, - unit and functional tests. We also include - performance tests in some libraries.

-

Remember that each point in this test universe may imply different tools - and different development practices. When talking about tests, this is - important to have this schema in minds and to wonder where our problematic - locates.

- -

Test, test case and test - suite

+

L'axe "Support de conception" décrit la visibilité que nous + avons sur le System Under Test : soit + boite noire ou boite blanche. Leurs + significations sont différentes suivant le contexte mais nous pouvons + considérer un système comme une boite blanche si nous regardons et utilisons + ce qui est dans la boite, sinon + la boite est noire. Par exemple, pour les tests unitaires, disons que le SUT + est une fonction, les tests boite noire vont considérer seulement les entrées + et les sorties de la fonction sans considérer son corps (même si elle lit ou + écrit des variables globales, flux etc.). D'un autre côté, les tests boite + blanche vont considérer le corps de la fonction et la stratégie de test sera + totalement différente. Nous n'attendons pas la même chose d'un système boite + noire ou boite blanche.

+

L'axe "Taille du système" décrit à quel niveau (ou altitude) + nous testons : du plus bas, unitaire (une fonction ou une + méthode) au plus haut, tout le système, ce qui inclut les + composants (ensemble de fonctions) et + l'intégration des composants dans d'autres composants, qui, + ensemble, forment le système. Tous les niveaux sont important : ce n'est pas + parce qu'une fontion fait ce qu'elle est supposée faire qu'elle s'intégrera + correctement avec une autre.

+ +

Enfin, l'axe "Type de test" décrit l'objectif des tests : + fonctionnel (“tout fonctionne comme prévu et c'est + tout“), robustesse (“il n'est pas possible de mettre + le système dans un état d'erreur si nous faisons quelque chose d'imprévu“), + performance (“le système supporte une forte charge + et se comporte correctement dans ces conditions“) etc.

+

Dans Hoa, nous avons des tests boite blanche et + boite noire, unitaires et + fonctionnels. Nous incluons également des tests de performance + dans certaines bibliothèques.

+

Souvenez-vous que chaque point dans cet univers des tests peut impliquer + différents outils et différentes pratiques de développement. Quand nous parlons + de tests, il est important de garder ce schéma à l'esprit et de situer ou se + trouve notre problématique.

+ +

Test, cas de test et + suite de test

+ +

Officiellement, un test d'un SUT est un ensemble de données + (appelées données de test) qui alimentent les valeurs des arguments (aussi + appelés entrées) d'un SUT. Un cas de test est une paire + composée d'un état (le contexte dans lequel est exécuté le test) et un test. + Une suite de test est ensemble de cas de test. Par conséquent, + il y a deux états du point du vue du test : un pré-état + — avant l'exécution du SUT — et un post-état — après + l'exécution —.

Formally, a test of a SUT is a set of data (called test data) that fixes the values of the arguments (also called inputs) of the From a889a8d8264833a8a45132b2c2181e62ed74ba1a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rapha=C3=ABl=20Emourgeon?= Date: Mon, 26 Oct 2015 22:19:45 +0100 Subject: [PATCH 07/28] Continue. --- Documentation/Fr/Index.xyl | 57 ++++++++++++++++---------------------- 1 file changed, 24 insertions(+), 33 deletions(-) diff --git a/Documentation/Fr/Index.xyl b/Documentation/Fr/Index.xyl index 2260cdb..c4d79eb 100644 --- a/Documentation/Fr/Index.xyl +++ b/Documentation/Fr/Index.xyl @@ -118,46 +118,37 @@ de tests, il est important de garder ce schéma à l'esprit et de situer ou se trouve notre problématique.

-

Test, cas de test et +

Test, scénario de test et suite de test

Officiellement, un test d'un SUT est un ensemble de données (appelées données de test) qui alimentent les valeurs des arguments (aussi - appelés entrées) d'un SUT. Un cas de test est une paire + appelés entrées) d'un SUT. Un scénario de test est une paire composée d'un état (le contexte dans lequel est exécuté le test) et un test. - Une suite de test est ensemble de cas de test. Par conséquent, - il y a deux états du point du vue du test : un pré-état - — avant l'exécution du SUT — et un post-état — après - l'exécution —. - -

Formally, a test of a SUT is a set of data (called test - data) that fixes the values of the arguments (also called inputs) of the - SUT. A test case is a pair composed of a state (the context - in which the test is executed) and a test. A test suite is - a set of test cases. Therefore, there is two states from the test point of - view: A pre-state —before the execution of the SUT— and a - post-state —after the execution—.

-

Building the pre-state is something crucial: The goal is to put the SUT into a - specific (pre-)state in order to test it. The part of the test case - responsible to create the pre-state is called the preamble. - Thus, the preambler is a code that puts the SUT into a specific state.

-

So, when writing a test case, we will have 3 items to consider:

+ Une suite de test est ensemble de scénario de test. Par + conséquent, il y a deux états du point du vue du test : un + pré-état — avant l'exécution du SUT — et un + post-état — après l'exécution —.

+

Construire le pré-état est critique : le but est de mettre le SUT dans un + (pré-)état spécifique afin de le tester. La partie du scénario de test responsable + de créer le pré-état est appelé le préambule. Ainsi, le + préambler est le code qui met le SUT dans un état spécifique.

+

Ainsi, en écrivant un scénario de test, nous aurons 3 éléments à considérer :

    -
  1. The preamble, to put the SUT into a specific - state,
    2. -
  2. The execution, to run the SUT and get a result,
    3. -
  3. The oracle, to compute the test verdict (based on the - execution result and the post-state).
    4. +
  4. Le préambule, pour mettre le SUT dans un état spécifique,
    5. +
  5. L'exécution, pour exécuter le SUT et obtenir un résultat,
    6. +
  6. L'oracle, pour évaluer le verdict (basé sur le résultat + de l'exécution et le post-état).
-

The oracle consists of a sequence of assertions: “Is this value equals - to…?”, “Is this value changed this way…?” etc. It is supposed to be able to - check the form of some data as much as comparing other data between the - pre-state and the post-state.

-

In a test case, we represent and introduce the preamble, the execution and - the oracle respectively by the given, when and - then keywords. This will be detail hereinafter.

- -

Test framework

+

L'oracle consiste en une séquence d'assertions : “Est-ce que cette valeur + est égale à… ?”, “Est-ce que la valeur a changé de cette façon… ?” etc. Il + est censé pouvoir vérifier la forme de certaines données mais également + comparer des données entre le pré et le post-état.

+

Dans un scénario de test, nous représentons et introduisons le préambule, + l'exécution et l'oracle respectivement par les mots clés given, + when et then. Ceci sera détaillé ci-après.

+ +

Framework de test

Hoa did not developed its own test framework for several reasons. The main one is that this is a laborious task. It implies more development, more tools From e3e98057db685134a277a5311eeb6386e14d615f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rapha=C3=ABl=20Emourgeon?= Date: Mon, 26 Oct 2015 22:23:29 +0100 Subject: [PATCH 08/28] Fix typo. --- Documentation/Fr/Index.xyl | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Documentation/Fr/Index.xyl b/Documentation/Fr/Index.xyl index c4d79eb..bbb614f 100644 --- a/Documentation/Fr/Index.xyl +++ b/Documentation/Fr/Index.xyl @@ -135,8 +135,8 @@ préambler est le code qui met le SUT dans un état spécifique.

Ainsi, en écrivant un scénario de test, nous aurons 3 éléments à considérer :

    -
  1. Le préambule, pour mettre le SUT dans un état spécifique,
    2. -
  2. L'exécution, pour exécuter le SUT et obtenir un résultat,
    3. +
  3. Le préambule, pour mettre le SUT dans un état spécifique ;
    4. +
  4. L'exécution, pour exécuter le SUT et obtenir un résultat ;
  5. L'oracle, pour évaluer le verdict (basé sur le résultat de l'exécution et le post-état).
From e647f2369b585321249c21cdf394e26e25d9320b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rapha=C3=ABl=20Emourgeon?= Date: Tue, 24 Nov 2015 23:45:41 +0100 Subject: [PATCH 09/28] Continue. --- Documentation/Fr/Index.xyl | 25 +++++++++++++------------ 1 file changed, 13 insertions(+), 12 deletions(-) diff --git a/Documentation/Fr/Index.xyl b/Documentation/Fr/Index.xyl index bbb614f..6576fc0 100644 --- a/Documentation/Fr/Index.xyl +++ b/Documentation/Fr/Index.xyl @@ -150,18 +150,19 @@

Framework de test

-

Hoa did not developed its own test framework for several reasons. The main - one is that this is a laborious task. It implies more development, more tools - to maintain, less people focused on Hoa etc. Instead, we prefer to choose a - good project to rely on and contribute to it. Then, we choose - atoum, “a simple, modern and intuitive test - framework”.

-

Thus, Hoa\Test is the basis to test all Hoa's libraries. It - wraps atoum and it aims at being a bridge between Hoa's features and - atoum's features. It also adds some features when needed. This is more than - an abstract layer on top of atoum. Hoa\Test also provides its - own command-line to run the tests with everything pre-packaged. Consequently, - Hoa\Test provides a ready-to-use test environment targeting +

Hoa n'a pas développé son propre framework de tests pour plusieurs raisons. + La raison principale étant que c'est une tâche laborieuse. Cela implique plus + de développement, plus d'outils à maintenir, moins de gens concentrés sur Hoa + etc. A la place, nous préférons choisir un bon projet sur lequel nous + appuyer et y contribuer. Nous avons opté pour atoum, + “un framework de test simple, moderne et intuitif”.

+

Ainsi, la bibliothèque Hoa\Test est la base pour tester toutes + les bibliothèques de Hoa. Elle intègre atoum et vise à être un pont entre + les fonctionnalités de Hoa et atoum. Elle ajoute également quelques + fonctionnalités si nécessaire. Elle est plus qu'une couche d'abstraction au + dessus d'atoum. Hoa\Test fournit également sa propre ligne de + commande pour exécuter les tests avec everything pre-packaged. En conséquence, + Hoa\Test fournit un environnement de test prêt à l'emploi pour Hoa.

One shall not be surprised to see some contributors of Hoa as contributors of atoum. The two communities are strongly linked. Hoa also provides From 5ff4ada6ffe6378e674828fddb7a6f6987cdca67 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rapha=C3=ABl=20Emourgeon?= Date: Tue, 24 Nov 2015 23:51:15 +0100 Subject: [PATCH 10/28] Continue. --- Documentation/Fr/Index.xyl | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/Documentation/Fr/Index.xyl b/Documentation/Fr/Index.xyl index 6576fc0..ffaf9b8 100644 --- a/Documentation/Fr/Index.xyl +++ b/Documentation/Fr/Index.xyl @@ -164,18 +164,18 @@ commande pour exécuter les tests avec everything pre-packaged. En conséquence, Hoa\Test fournit un environnement de test prêt à l'emploi pour Hoa.

-

One shall not be surprised to see some contributors of Hoa as contributors - of atoum. The two communities are strongly linked. Hoa also provides - official contributions to atoum like - the - atoum/praspel-extension extension and some other - extensions are based on Hoa, like - the - atoum/ruler-extension extension which is based on - the Hoa\Ruler library, also - used by Hoa\Test. Even some atoum's extensions are tested with - atoum and Hoa (with atoum/praspel-extension). The loop is - complete.

+

Il ne faut pas être surpris de voir certains contributeurs de Hoa contribuer + également à atoum. Les deux communautés sont étroitement liées. Hoa fournit + également des contributions officielles à atoum tel que + l'extension + atoum/praspel-extension et d'autres extensions sont basées sur + Hoa, par exemple + l'extension + atoum/ruler-extension qui est basée sur + la bibliothèque Hoa\Ruler, + également utilisée par Hoa\Test. Certaines extensions de atoum + sont même testées avec atoum et Hoa (avec atoum/praspel-extension). + La boucle est bouclée.

Research papers

From 1bdb95efe9228a1dd1eb0d8e5a050837110e64b6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rapha=C3=ABl=20Emourgeon?= Date: Wed, 25 Nov 2015 00:03:07 +0100 Subject: [PATCH 11/28] Continue. --- Documentation/Fr/Index.xyl | 33 +++++++++++++++++---------------- 1 file changed, 17 insertions(+), 16 deletions(-) diff --git a/Documentation/Fr/Index.xyl b/Documentation/Fr/Index.xyl index ffaf9b8..0e2e7af 100644 --- a/Documentation/Fr/Index.xyl +++ b/Documentation/Fr/Index.xyl @@ -177,31 +177,32 @@ sont même testées avec atoum et Hoa (avec atoum/praspel-extension). La boucle est bouclée.

-

Research papers

+

Etudes

-

Several research papers (articles, journal and a PhD - thesis) have been published about Hoa\Test, - Hoa\Praspel and Hoa\Realdom:

+

Plusieurs études (articles, journaux et une thèse de + doctorat) ont été publiées à propos de Hoa\Test, + Hoa\Praspel et Hoa\Realdom:

-

These papers are about test data generation and - validation, including Design-by-Contract and Contract-based - Testing in PHP, along with Grammar-based Testing and Solver-based Testing.

+

Ces documents évoquent la génération et de la + validation de données de test, incluant le Design-by-Contract + et le Contract-based-Testing en PHP, ainsi que le Grammar-based Testing et le + Solver-based Testing.

Writing tests

From 98679672d7696d1382371cbce9759a94b874e4b1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rapha=C3=ABl=20Emourgeon?= Date: Sun, 29 Nov 2015 22:52:43 +0100 Subject: [PATCH 12/28] Continue. --- Documentation/Fr/Index.xyl | 31 ++++++++++++++++--------------- 1 file changed, 16 insertions(+), 15 deletions(-) diff --git a/Documentation/Fr/Index.xyl b/Documentation/Fr/Index.xyl index 0e2e7af..cb7560f 100644 --- a/Documentation/Fr/Index.xyl +++ b/Documentation/Fr/Index.xyl @@ -204,21 +204,22 @@ et le Contract-based-Testing en PHP, ainsi que le Grammar-based Testing et le Solver-based Testing.

-

Writing tests

- -

Each library provides a Test/ directory at the root of the - repository. This is where tests are located. Automated unit tests can be found in - the Test/Unit/ directory while automatically generated unit tests can - be found in the Test/Praspel/Unit/ directory (not by default, - they must be generated first).

- -

Automated unit tests

- -

In Hoa, a test suite is represented by a file, containing a class. A test - case is a method in this class, expressing the preamble, the execution of - the SUT and the oracle. The template of a test suite is then the following - (let's say for the Test/Unit/Bar.php test suite of the - Hoa\Foo library):

+

Ecrire des tests

+ +

Chaque bibliothèque dispose d'un dossier Test/ à la racine de + son dépôt. C'est dans ce dossier que se trouvent les tests. Les tests unitaires + automatisés sont dans le dossier Test/Unit/ tandis que les tests + unitaires générés automatiquement se trouvent dans le dossier + Test/Praspel/Unit/ (pas par défaut, ils doivent d'abord être + générés).

+ +

Tests unitaires automatisés

+ +

Dans Hoa, une suite de test est représentée par un fichier contenant une + classe. Un cas de test est une méthode de cette classe qui exprime le préambule, + l'exécution du SUT et l'oracle. Le modèle d'une suite de test est le suivant + (supposons la suite de test Test/Unit/Bar.php de la bibliothèque + Hoa\Foo) :

namespace Hoa\Foo\Test\Unit;
 
 use Hoa\Foo\Bar as SUT;

From 648de18bd8e7becd918553e18338e8744947a16b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Rapha=C3=ABl=20Emourgeon?= 
Date: Sun, 17 Jul 2016 22:44:56 +0200
Subject: [PATCH 13/28] Continue (yeah !).

---
 Documentation/Fr/Index.xyl | 33 +++++++++++++++++----------------
 1 file changed, 17 insertions(+), 16 deletions(-)

diff --git a/Documentation/Fr/Index.xyl b/Documentation/Fr/Index.xyl
index cb7560f..e8b4f49 100644
--- a/Documentation/Fr/Index.xyl
+++ b/Documentation/Fr/Index.xyl
@@ -232,23 +232,24 @@ class Bar extends Test\Unit\Suite
         // test case.
     }
 }
-

We define an alias SUT to the current System Under Test. In a - unit test context, this is a method or a class. We can also declare the - CUT alias, standing for Class Under Test, and LUT - for Library Under Test. LUT is useful if we need to access to - other classes in the same library. Because they are unit tests, we should not - use other classes but remember that a test case is composed of a preamble and - it needs to be build. In this case, LUT could be defined to +

On définit un alias SUT pour le System Under Test + actuel. Dans le contexte d'un test unitaire, c'est une méthode ou une classe. + On peut également déclarer l'alias CUT, pour Class Under Test, + et LUT pour Library Under Test. LUT + est utile si nous devons accéder à d'autres classes de la même bibliothèque. + Etant donné que ce sont des tests unitaires, nous ne devons pas utiliser d'autres + classes mais rappelez-vous qu'un case de test est composé d'un préambule et + qu'il doit être construit. Dans ce cas, LUT peut être défini comme Hoa\Foo.

-

The Bar class extends the Hoa\Test\Unit\Suite - class, which defines a unit test suite. It offers all the test API we need - to write tests.

-

Test cases are public method. They do not use a camel case notation but an - underscore lower-cased notation. They must be prefixed by - case_. The template of a test case must follow the preamble, - execution and oracle principle, respectively represented by the - given, when and then keywords, and - thus must be written as follows:

+

La classe Bar étends la classe Hoa\Test\Unit\Suite + qui définit une suite de tests unitaires. Elle offre toute l'API de test + dont on a besoin pour écrire des tests.

+

Les cas de test sont des méthodes publiques. Elles n'utilisent pas la + notation camel case mais une notation underscore lower-cased. + Elles doivent être préfixées par case_. Un cas de test doit + suivre la structure préambule, exécution et oracle, représentés respectivement + par les mots clés given, when et then. + Un cas de test doit donc être écrit de la manière suivante :

public function case_classic()
 {
     $this

From bf3d732966426b9c9d69a7d18da6614fdc97e693 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Rapha=C3=ABl=20Emourgeon?= 
Date: Mon, 18 Jul 2016 22:17:02 +0200
Subject: [PATCH 14/28] Continue.

---
 Documentation/Fr/Index.xyl | 38 ++++++++++++++++++++------------------
 1 file changed, 20 insertions(+), 18 deletions(-)

diff --git a/Documentation/Fr/Index.xyl b/Documentation/Fr/Index.xyl
index e8b4f49..4e4a498 100644
--- a/Documentation/Fr/Index.xyl
+++ b/Documentation/Fr/Index.xyl
@@ -265,10 +265,11 @@ class Bar extends Test\Unit\Suite
         ->then
             ->…;
 }
-

The given and when “control flow structures” are - function calls with an unbounded arity. They are void methods, they do - nothing. The goal is not to pass something to them but to declare variables, - to establish the preamble and to execute the test. For instance:

+

Les "structures de contrôle" given et when sont + des appels de fonction avec une arité non-liée. Ce sont des méthodes vides, + elles ne font rien. Le but n'est pas de leur passer quelque chose mais de + déclarer des variables pour établir le préambule et exécuter le test. Par + exemple :

public function case_sum()
 {
     $this
@@ -283,7 +284,7 @@ class Bar extends Test\Unit\Suite
             ->integer($result)
                 ->isEqualTo(3);
 }
-

This is strictly equivalent to write:

+

Ceci est strictement équivalent à écrire :

public function case_sum()
 {
     // Given:
@@ -294,16 +295,16 @@ class Bar extends Test\Unit\Suite
     // Then:
     $this->integer($result)>-isEqualTo(3);
 }
-

We however use the first form, which is clearer: Indentation, special - keywords (through method names) and force us to clearly separate these - 3 parts: Preamble, test execution and oracle.

-

The $result variable is special. It must - always hold the result of the test execution, i.e. the - result of the SUT's return statement. This - is a convention.

-

One test case can contain multiple test executions with multiple oracles - (for instance if a SUT returns different results according to the time). - Then, the test case must be written as follows:

+

Nous utilisons toutefois la première forme qui est plus claire, l'indentation + et les mots clés spéciaux (au travers des noms de méthodes) nous forcent à + séparer clairement les 3 parties : préambule, exécution du test et oracle.

+

La variable $result est spéciale. Elle + doit toujours contenir le résultat de l'exécution du test, + i.e. le résultat de la déclaration return + du SUT. Ceci est une convention.

+

Un cas de test peut contenir plusieurs exécutions avec des oracles multiples + (par exemple si un SUT retourne différent résultats en fonction du temps). + Ainsi, le cas de test doit être écrit comme ceci :

public function case_classic()
 {
     $this
@@ -320,9 +321,10 @@ class Bar extends Test\Unit\Suite
         ->then
             ->…;
 }
-

Assertions are always used after the then part and most of the - time has the form assertion-group->assertion. - We can link assertion groups too. For instance:

+

Les assertions sont toujours utilisées après la partie then et + ont la plupart du temps la forme + assertion-groupe->assertion. Nous pouvons + également lier des groupes d'assertions. Par exemple :

public function case_sum()
 {
     $this

From 83ca5b5378d5daf58ff7a215d4fccc493da3af16 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Rapha=C3=ABl=20Emourgeon?= 
Date: Wed, 20 Jul 2016 08:09:51 +0200
Subject: [PATCH 15/28] Continue.

---
 Documentation/Fr/Index.xyl | 20 ++++++++++----------
 1 file changed, 10 insertions(+), 10 deletions(-)

diff --git a/Documentation/Fr/Index.xyl b/Documentation/Fr/Index.xyl
index 4e4a498..bb4514c 100644
--- a/Documentation/Fr/Index.xyl
+++ b/Documentation/Fr/Index.xyl
@@ -342,16 +342,16 @@ class Bar extends Test\Unit\Suite
             ->string((string) $result)
                 ->isNotEmpty();
 }
-

The list of all - assertions can be find on atoum's documentation. Even if this is pretty - natural to write assertions because it is close to “human conventions”, - sometimes this is useful to discover that a specific assertion already exists, - like float->isNearlyEqualTo which compares two floats as - expected most of the time. So feel free to check atoum's documentation - often!

- -

Automatic test data - generation

+

La liste de toutes + les assertions peut être trouvée dans la documentation d'atoum. Même s'il + est naturel d'écrire des assertions car elles sont proches des "conventions + humaines", il est parfois utile de découvrir qu'une assertion spécifique + existe déjà, comme par exemple float->isNearlyEqualTo qui compare + 2 flottants comme prévu la plupart du temps. N'hésitez pas à consulter la + documentation d'atoum régulièrement !

+ +

Génération automatique + des données de test

Hoa\Test includes the From fd2d4e52e47f7d5485c5aa81987ef970b5cc2b9d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rapha=C3=ABl=20Emourgeon?= Date: Tue, 26 Jul 2016 17:49:06 +0200 Subject: [PATCH 16/28] Continue. --- Documentation/Fr/Index.xyl | 29 ++++++++++++++--------------- 1 file changed, 14 insertions(+), 15 deletions(-) diff --git a/Documentation/Fr/Index.xyl b/Documentation/Fr/Index.xyl index bb4514c..f592e37 100644 --- a/Documentation/Fr/Index.xyl +++ b/Documentation/Fr/Index.xyl @@ -353,21 +353,20 @@ class Bar extends Test\Unit\Suite

Génération automatique des données de test

-

Hoa\Test includes - the - atoum/praspel-extension extension. This extension - includes the Hoa\Praspel - library and the - Hoa\Realdom library inside atoum. When doing manual or - automated tests, this extension can be used to automatically generate - test data.

-

All we need is to describe a realistic domain (see - the Hoa\Realdom library) with - the realdom assertion group and then use the sample - “assertion” (internally this is a handler but the syntax is the same) - to generate one value or sampleMany to generate many values. For - instance, to automatically generate an integer in the interval 7 to 13 or 42 - to 153:

+

Hoa\Test inclut + + l'extension Hoa\Praspel. Cette extension inclut + la bibliothèque Hoa\Praspella bibliothèque Hoa\Realdom + dans atoum. Lors de tests manuels ou automatisés, cette extension peut être + utilisée pour générer automatiquement des données de test.

+

Tout ce que nous avons à faire est de décrire un domaine réaliste (voir la + bibliothèque Hoa\Realdom) avec + l'assertion de groupe realdom et utiliser ensuite l'“assertion” + sample (à l'interne c'est un handler mais la syntaxe est + la même) pour générer une valeur ou sampleMany pour générer + plusieurs valeurs. Par exemple, pour générer automatiquement des entiers dans + l'interval 7 à 13 ou 42 à 153:

public function case_sum()
 {
     $this

From f834e7f9338e442d13d50e832e8607616c3dec7a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Rapha=C3=ABl=20Emourgeon?= 
Date: Fri, 29 Jul 2016 17:55:32 +0200
Subject: [PATCH 17/28] Continue.

---
 Documentation/Fr/Index.xyl | 40 +++++++++++++++++++-------------------
 1 file changed, 20 insertions(+), 20 deletions(-)

diff --git a/Documentation/Fr/Index.xyl b/Documentation/Fr/Index.xyl
index f592e37..34a1b04 100644
--- a/Documentation/Fr/Index.xyl
+++ b/Documentation/Fr/Index.xyl
@@ -383,24 +383,24 @@ class Bar extends Test\Unit\Suite
         ->then
           ->…;
 }
-

Actually, atoum/praspel-extension provides 3 asserters to - generate data and 1 asserter to validate data:

+

Actuellement, atoum/praspel-extension fournit 3 asserters pour + générer des données et 1 asserter pour les valider :

    -
  1. realdom to create a a realistic domain disjunction (see the - or in the previous example),
    2. -
  2. sample to generate one datum from a realistic domains - disjunction,
    3. -
  3. sampleMany to generate several data,
    4. -
  4. predicate to validate a datum against a realistic domain - disjunction.
    5. +
  5. realdom pour créer une disjonction de domaine réaliste + (or dans l'exemple précédent),
    6. +
  6. sample pour générer une donnée depuis une disjonction de + domaine réaliste,
    7. +
  7. sampleMany pour générer plusieurs données,
    8. +
  8. predicate pour valider une données en fonction d'une + disjonction de domaine réaliste.
-

Hoa\Realdom provides a standard realistic domain collection, - which includes very useful ones, like regex that describes a - regular expression (in the PCRE format). - Thus, we are able to automatically generate a datum against - or validate data matching regular - expressions. The following example generate one string similar to - an email address:

+

Hoa\Realdom fournit une collection de domaines réaliste + standards, dont certains très utiles, comme regex qui décrit une + expression régulière (dans le format PCRE). + Ainsi, nous sommes capable de générer automatiquement ou + valider une donnée qui correspond à une expression + régulière. L'exemple suivant génère une chaîne similaire à une + adresse email :

$this
     ->given(
         $email = $this->sample(
@@ -409,8 +409,8 @@ class Bar extends Test\Unit\Suite
         …
     )
     ->…
-

The following example declare a realistic domain representing a date with - the d/m H:i format, between yesterday and the next Monday:

+

L'exemple ci-dessous déclare un domaine réaliste qui représente une date + avec le format d/m H:i, entre hier et lundi prochain :

$this
     ->given(
         $_date = $this->realdom->date(
@@ -422,9 +422,9 @@ class Bar extends Test\Unit\Suite
         )
     )
     ->…
-

Then, to generate one date:

+

Ensuite, pour générer une date :

$this->sample($_date)
-

Or to sample 42 dates:

+

Ou pour en générer 42 :

$this->sampleMany($_date, 42)

Similarly, booleans, arrays, classes, colors, strings based on grammars etc. can be generated… but also validated! The predicate From a82bc94d9cc104d7da15d550cf92ce4381e393ef Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rapha=C3=ABl=20Emourgeon?= Date: Sat, 13 Aug 2016 14:34:43 +0200 Subject: [PATCH 18/28] Continue. --- Documentation/Fr/Index.xyl | 33 ++++++++++++++++----------------- 1 file changed, 16 insertions(+), 17 deletions(-) diff --git a/Documentation/Fr/Index.xyl b/Documentation/Fr/Index.xyl index 34a1b04..c21fea3 100644 --- a/Documentation/Fr/Index.xyl +++ b/Documentation/Fr/Index.xyl @@ -426,13 +426,13 @@ class Bar extends Test\Unit\Suite 

$this->sample($_date)

Ou pour en générer 42 :

$this->sampleMany($_date, 42)
-

Similarly, booleans, arrays, classes, colors, strings based on grammars - etc. can be generated… but also validated! The predicate - asserter is a real one, contrary to realdom, sample - and sampleMany. By nature, it computes a boolean: Either - true or - false. It can be used on a realistic domain - disjunction, for instance:

+

De la même manière, des booléens, tableaux, classes, couleurs, chaînes basés + sur des grammaires etc. peuvent être générées… mais également validés ! + Contrairement à realdom, sample et + sampleMany, predicate est un vrai asserter. Par + nature, il calcule un booléen : soit true or + false. Il peut être utilisé sur une + disjonction de domaine réaliste, par exemple :

$this
     ->given(
         $_date = $this->realdom->date(
@@ -447,16 +447,15 @@ class Bar extends Test\Unit\Suite
     ->when($result = SUT::compute($stuff)
     ->then
         ->predicate($_date, $result);
-

In the above example, the _date realistic domain is described, - not to generate a datum but to validate the result from the SUT.

-

To get more information about Grammar-based Testing, please, see - the Hoa\Compiler library. - To get more information about Solver-based Testing, please, see the - the Hoa\Realdom library. In - all cases, please, see our research papers.

- -

Automatically generated - tests

+

Dans l'exemple ci-dessus, le domaine réaliste _date est décrit, + non pas pour générer une donnée, mais pour valider le résultat du SUT.

+

Pour obtenir plus d'informations concernant le Grammar-based Testing, voir + la bibliothèque Hoa\Realdom. + Dans tous les cas, veuillez consulter + nos études.

+ +

Tests générés + automatiquement

This section has been addressed by a PhD thesis and several research papers. However, tools are not From 43eb50e5e8f441088f1f73d4a361c275e0a666dd Mon Sep 17 00:00:00 2001 From: Alexis von Glasow Date: Fri, 3 Mar 2017 23:21:09 +0100 Subject: [PATCH 19/28] fix typo --- Documentation/Fr/Index.xyl | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/Documentation/Fr/Index.xyl b/Documentation/Fr/Index.xyl index c21fea3..3ff6a6e 100644 --- a/Documentation/Fr/Index.xyl +++ b/Documentation/Fr/Index.xyl @@ -3,7 +3,7 @@

Assurer la qualité du logiciel n'est pas facile. La bibliothèque Hoa\Test fournit plusieurs outils pour écrire et - exécuter des tests, générer des données de tests ou même des tests eux-même + exécuter des tests, générer des données de tests ou même des tests eux-mêmes etc. Ceci est la base pour tester les bibliothèques de Hoa. Des articles de recherche ont été publiés et implémentés dans Hoa\Test et des bibliothèques connexes (comme Hoa\Praspel, @@ -61,7 +61,7 @@ automatiquement les tests (s'il vous plaît, allez voir la bibliothèque Hoa\Praspel ou les rapports de recherches que nous avons publiés ci-dessous pour en apprendre - plus sur les paragdimes de Design-by-Contract et + plus sur les paradigmes de Design-by-Contract et Contact-based Testing). Les tests automatiques ont deux sous-catégories : les tests en ligne ou hors-ligne. En ligne signifie @@ -113,7 +113,7 @@ boite noire, unitaires et fonctionnels. Nous incluons également des tests de performance dans certaines bibliothèques.

-

Souvenez-vous que chaque point dans cet univers des tests peut impliquer +

Souvenez-vous que chaque point dans cet univers de tests peut impliquer différents outils et différentes pratiques de développement. Quand nous parlons de tests, il est important de garder ce schéma à l'esprit et de situer ou se trouve notre problématique.

@@ -236,7 +236,7 @@ class Bar extends Test\Unit\Suite actuel. Dans le contexte d'un test unitaire, c'est une méthode ou une classe. On peut également déclarer l'alias CUT, pour Class Under Test, et LUT pour Library Under Test. LUT - est utile si nous devons accéder à d'autres classes de la même bibliothèque. + est utile si nous devons accéder à d'autres classes de la même bibliothèque. Etant donné que ce sont des tests unitaires, nous ne devons pas utiliser d'autres classes mais rappelez-vous qu'un case de test est composé d'un préambule et qu'il doit être construit. Dans ce cas, LUT peut être défini comme @@ -343,7 +343,7 @@ class Bar extends Test\Unit\Suite ->isNotEmpty(); }

La liste de toutes - les assertions peut être trouvée dans la documentation d'atoum. Même s'il + les assertions peut être trouvée dans la documentation d'atoum. Même s'il est naturel d'écrire des assertions car elles sont proches des "conventions humaines", il est parfois utile de découvrir qu'une assertion spécifique existe déjà, comme par exemple float->isNearlyEqualTo qui compare @@ -356,7 +356,7 @@ class Bar extends Test\Unit\Suite

Hoa\Test inclut l'extension Hoa\Praspel. Cette extension inclut - la bibliothèque Hoa\Praspella bibliothèque Hoa\Praspel et la bibliothèque Hoa\Realdom dans atoum. Lors de tests manuels ou automatisés, cette extension peut être utilisée pour générer automatiquement des données de test.

@@ -366,7 +366,7 @@ class Bar extends Test\Unit\Suite sample (à l'interne c'est un handler mais la syntaxe est la même) pour générer une valeur ou sampleMany pour générer plusieurs valeurs. Par exemple, pour générer automatiquement des entiers dans - l'interval 7 à 13 ou 42 à 153:

+ l'intervalle 7 à 13 ou 42 à 153:

public function case_sum()
 {
     $this

From b9ecef8241b5b68038b57963ed74b208f3715ab2 Mon Sep 17 00:00:00 2001
From: Alexis von Glasow 
Date: Mon, 6 Mar 2017 13:15:50 +0100
Subject: [PATCH 20/28] Translate 'Conclusion'

---
 Documentation/Fr/Index.xyl | 27 +++++++++++++++------------
 1 file changed, 15 insertions(+), 12 deletions(-)

diff --git a/Documentation/Fr/Index.xyl b/Documentation/Fr/Index.xyl
index 3ff6a6e..da8aa03 100644
--- a/Documentation/Fr/Index.xyl
+++ b/Documentation/Fr/Index.xyl
@@ -718,18 +718,21 @@ $file  = new Hoa\File\ReadWrite('hoa://Test/Vfs/Foo?atime=' . $aTime);
Conclusion
 
-  
The Hoa\Test library is a set of tools to make white
-  box or black box, unit or
-  functional, automated and
-  automatic unit tests. This is more than a wrapper around
-  atoum: It provides a test structure and
-  conventions, a virtual file system and
-  extensions to automatically generate test
-  data, automatically generate tests or to get a powerful test
-  filtering system. Grammar-based Testing, Solver-based
-  Testing, Random-based Testing, Contract-based Testing… all these paradigms
-  live in Hoa\Test. Several research
-  papers have been published in major test literature and conferences.

+  
La bibliothèque Hoa\Test est un ensemble d'outils permettant
+  de réaliser des tests unitaires ou
+  fonctionnels, automatisés ou
+  automatiques, soit en boîtes blanches, soit
+  en boîtes noires. Elle est plus qu'un wrapper autour d'atoum: Elle fournit une structure de test et de
+  conventions, un système de fichiers virtuel et des
+  extensions pour générer automatiquement des
+  données de test, générer automatiquement des tests ou d'obtenir un puissant
+  système de filtrage de test.  Tests basés sur la grammaire,
+  tests basés sur le solveur, tests basés sur des résultats aléatoires, tests
+  basés sur des contrats… tous ces paradigmes se trouvent dans
+  Hoa\Test. Plusieurs articles de
+  recherche ont été publiés dans des publications et des conférences
+  importantes sur les tests.

 
 
 

From 78d7afa12ce3e560066deb6eee66b2b4cbe1fc4b Mon Sep 17 00:00:00 2001
From: Alexis von Glasow 
Date: Mon, 6 Mar 2017 13:25:34 +0100
Subject: [PATCH 21/28] Translate 'Permission'

---
 Documentation/Fr/Index.xyl | 15 ++++++++-------
 1 file changed, 8 insertions(+), 7 deletions(-)

diff --git a/Documentation/Fr/Index.xyl b/Documentation/Fr/Index.xyl
index da8aa03..0e5292d 100644
--- a/Documentation/Fr/Index.xyl
+++ b/Documentation/Fr/Index.xyl
@@ -690,9 +690,10 @@ var_dump($file->readAll());
 
   
Permissions

 
-  
To change the permissions, either the specific stream permission functions
-  can be used or we can set them directly by using the
-  permissions query string followed by an octal value; thus:

+  
Pour modifier les permissions, les fonctions d'autorisation de flux
+  spécifiques peuvent être utilisées ou nous pouvons les définir directement en
+  utilisant la chaîne de requête de permissions suivie d'une valeur octale;
+  Ainsi:

   
$file = new Hoa\File\ReadWrite('hoa://Test/Vfs/Foo?permissions=0644');
 var_dump($file->getReadablePermissions());
 
@@ -700,10 +701,10 @@ var_dump($file->getReadablePermissions());
  * Will output:
  *     string(10) "-rw-r--r--"
  */

-  
As any query strings, we can concatenate key-values by using the
-  & symbol. For instance,
-  type=directory&permissions=0644 represents a directory
-  with the 0644 permissions.

+  
Comme toutes requêtes, nous pouvons concatener des clefs-valeurs en
+  utilisant le symbole &. Par exemple,
+  type=directory&permissions=0644
 représente un
+  répertoire avec les autorisations 0644.

 
   
Access-, change- and
   modify-time


From d5f7c9ac380435b425a90794dcfc2ee29c238cf6 Mon Sep 17 00:00:00 2001
From: Alexis von Glasow 
Date: Mon, 11 Sep 2017 14:12:18 +0200
Subject: [PATCH 22/28] translate 'run tests'

---
 Documentation/Fr/Index.xyl | 52 ++++++++++++++++++++------------------
 1 file changed, 27 insertions(+), 25 deletions(-)

diff --git a/Documentation/Fr/Index.xyl b/Documentation/Fr/Index.xyl
index 0e5292d..e4a9a69 100644
--- a/Documentation/Fr/Index.xyl
+++ b/Documentation/Fr/Index.xyl
@@ -451,38 +451,40 @@ class Bar extends Test\Unit\Suite
   non pas pour générer une donnée, mais pour valider le résultat du SUT.

   
Pour obtenir plus d'informations concernant le Grammar-based Testing, voir 
   la bibliothèque Hoa\Realdom.
-  Dans tous les cas, veuillez consulter 
-  nos études.

+  Dans tous les cas, veuillez consulter nos études.

 
   
Tests générés 
   automatiquement

 
-  
This section has been addressed by a PhD thesis and several
-  research papers. However, tools are not
-  stable yet and documentation is under-writing. Please, refer to
-  the Hoa\Praspel library to
-  get more information.

+  
Cette section a été soutenue par une thèse de doctorat et plusieurs articles de recherches. Cependant, ces outils ne
+  sont pas encore stable et la documentation est en cours d'écriture. Veuillez
+  vous référer à la bibliothèque
+  Hoa\Praspel pour plus d'informations.

 
-  
Run tests

+  
Exécuter les tests

 
-  
Most of the time, we will run tests from inside a library repository.
-  Composer will be required to install
-  dependencies of the library, which includes Hoa\Test as a
-  development dependency. Thus, from the root of the library repository:

+  
La plupart du temps, nous exécutons les tests à partir du dépôt de la
+  bibliothèque. Composer est nécessaire
+  pour installer ses dépendances, ce qui inclu
+  Hoa\Test comme une dépendance de développement. Ainsi, à partir
+  de la racine du dépôt de la bibliothèque:

   
$ composer install

-  
By default it will install development dependencies. If not, force it by
-  adding the --dev option.

-  
A vendor/ directory is then created. Inside this directory, we
-  will find the bin/hoa command (please, see
-  the Hoa\Cli library). Executing
-  this command without any option will list all available sub-commands for this
-  current installation. We should see the test commands. To execute tests, we
-  will use the test:run sub-command. We must provide the directory
-  where tests are stored, which is always Test/. Thus:

+  
Par défaut, composer va installer les dépendances de développement. Sinon,
+  vous pouvez le forcer en ajoutant l'option --dev.

+  
Un répertoire vendor/ est ainsi créé. À l'intérieur de ce
+  répertoire, nous trouvons la commande bin/hoa (veuillez vous
+  référer à la bibliothèque
+  Hoa\Cli). Lancer cette commande sans aucune option va lister
+  toutes les sous-commandes disponible pour cette installation. Nous devrions
+  voir les commandes de tests. Pour les exécuter, nous allons utiliser la
+  sous-commande test:run. Nous devons fournir un répertoire où les
+  tests sont écrits, c'est toujours Test/. Ainsi: 

   
$ vendor/bin/hoa test:run --directories Test/

-  
Note that the --directories option has a plural form. This is
-  because we can specify more than one directory name by using a comma.

-  
At this point, we will see test executing themselves.

+  
Notez que l'option --directories a une forme plurielle. C'est
+  parce que l'on peut spécifier plus d'un répertoire, les noms devant être
+  séparés par une virgule.

+  
À ce stade, nous verrons l'exécution des tests.

 
   
Interpreting the test
   result

@@ -703,7 +705,7 @@ var_dump($file->getReadablePermissions());
  */

Comme toutes requêtes, nous pouvons concatener des clefs-valeurs en utilisant le symbole &. Par exemple, - type=directory&permissions=0644

représente un + type=directory&permissions=0644 représente un répertoire avec les autorisations 0644.

Access-, change- and From f76651f0db70a3cc7261cc86e36525fed2b0d876 Mon Sep 17 00:00:00 2001 From: Alexis von Glasow Date: Fri, 15 Sep 2017 22:48:17 +0200 Subject: [PATCH 23/28] translate 'interpreting tests results' --- Documentation/Fr/Index.xyl | 41 +++++++++++++++++++------------------- 1 file changed, 21 insertions(+), 20 deletions(-) diff --git a/Documentation/Fr/Index.xyl b/Documentation/Fr/Index.xyl index e4a9a69..69feb47 100644 --- a/Documentation/Fr/Index.xyl +++ b/Documentation/Fr/Index.xyl @@ -466,7 +466,7 @@ class Bar extends Test\Unit\Suite

La plupart du temps, nous exécutons les tests à partir du dépôt de la bibliothèque. Composer est nécessaire - pour installer ses dépendances, ce qui inclu + pour installer ses dépendances, ce qui inclus Hoa\Test comme une dépendance de développement. Ainsi, à partir de la racine du dépôt de la bibliothèque:

$ composer install
@@ -486,33 +486,34 @@ class Bar extends Test\Unit\Suite séparés par une virgule.

À ce stade, nous verrons l'exécution des tests.

-

Interpreting the test - result

+

Interprété le résultat du test

+ +

Le rapport de test en ligne de commande utilise des couleurs pour indiquer le + verdicte du test: vert pour un succès, rouge pour un échec ou non + concluant. Dans le cas d'un succès, nous devrions voir:

-

The CLI test reporter will use colours to indicate the test - verdict: green for success, red for fail or inconclusive. In case - of a success, we should see:

Success (S tests, c/C methods, V void method, K skipped method, A assertions)!
-

where:

+

où:

    -
  • S is the number of test suites,
    • -
  • c and C are the numbers of - test cases,
    • -
  • V is the number of inconclusive test cases,
    • -
  • K is the number of skipped test cases,
    • -
  • A is the numbre of assertions.
    • +
  • S est le nombre de suite de tests,
    • +
  • c et C sont les nombres de + cas de tests,
    • +
  • V est le nombre de cas de tests non concluant,
    • +
  • K est le nombre de tests skipped,
    • +
  • A est le nombre d'assertions.
-

In case of a failure, we should see:

+

Dans le cas d'un échec, nous devrions voir:

Failure (S tests, c/C methods, V void method, K skipped method, …, F failure, E error, X exception)!
 > There is F failure:
 …
    -
  • F is the number of failed test cases,
    • -
  • E is the number of unexpected errors,
    • -
  • X is the number of unexpected exceptions.
    • +
  • F est le nombre de cas de tests ayant échoués,
    • +
  • E est le nombre d'erreurs inattendues,
    • +
  • X est le nombre d'exceptions inattendues.
-

For each failure description, a “diff” will be computed, i.e. a textual - differential representation of what we expect and what we got.

+

Pour chaque description d'échecs, un “diff” va être calculé, i.e. Une + représentation différentielle textuelle de ce qui est attendue et de ce que + nous avons.

Debugging mode

@@ -703,7 +704,7 @@ var_dump($file->getReadablePermissions()); * Will output: * string(10) "-rw-r--r--" */ -

Comme toutes requêtes, nous pouvons concatener des clefs-valeurs en +

Comme toutes requêtes, nous pouvons concaténer des clefs-valeurs en utilisant le symbole &. Par exemple, type=directory&permissions=0644 représente un répertoire avec les autorisations 0644.

From c4bcc216d325e1b1000856c2d1ed317b3615fd29 Mon Sep 17 00:00:00 2001 From: Alexis von Glasow Date: Tue, 19 Sep 2017 23:53:07 +0200 Subject: [PATCH 24/28] Translate 'Debugging mode' --- Documentation/Fr/Index.xyl | 110 ++++++++++++++++++------------------- 1 file changed, 55 insertions(+), 55 deletions(-) diff --git a/Documentation/Fr/Index.xyl b/Documentation/Fr/Index.xyl index 69feb47..ff039f9 100644 --- a/Documentation/Fr/Index.xyl +++ b/Documentation/Fr/Index.xyl @@ -24,14 +24,14 @@

Nature des tests

Un test est exécuté sur un System Under Test, - abrégé SUT, et est composé de deux parties :

+ abrégé SUT, et est composé de deux parties :

    -
  1. les données de test pour exécuter le SUT ; et
    2. +
  2. les données de test pour exécuter le SUT ; et
  3. un oracle, qui établit le - verdict du test : est-ce que les résultats de l'exécution et - l'état du SUT après son exécution sont ceux que nous attendions ou pas ?
    4. + verdict du test : est-ce que les résultats de l'exécution et + l'état du SUT après son exécution sont ceux que nous attendions ou pas ?
-

Les valeurs du verdict sont : succès, +

Les valeurs du verdict sont : succès, échec ou non conclusif. Un succès signifie que c'est ce que nous attendions, un échec signifie que ce n'est pas ce que nous attendions et non conclusif signifie qu'il n'est pas possible de donner une réponse. @@ -63,7 +63,7 @@ les rapports de recherches que nous avons publiés ci-dessous pour en apprendre plus sur les paradigmes de Design-by-Contract et Contact-based Testing). - Les tests automatiques ont deux sous-catégories : les tests + Les tests automatiques ont deux sous-catégories : les tests en ligne ou hors-ligne. En ligne signifie que les tests sont générés et exécutés en une seule passe, tandis que hors-ligne signifie que les tests sont générés et exécutés plus tard @@ -72,7 +72,7 @@

Dans Hoa nous avons aussi bien des tests automatisés que des tests hors-ligne automatiques.

Ceci est une classification générale des tests. Une plus précise est décrite - par le schéma ci-dessous qui explique quel type de test écrire :

+ par le schéma ci-dessous qui explique quel type de test écrire :

L'axe "Support de conception" décrit la visibilité que nous - avons sur le System Under Test : soit + avons sur le System Under Test : soit boite noire ou boite blanche. Leurs significations sont différentes suivant le contexte mais nous pouvons considérer un système comme une boite blanche si nous regardons et utilisons @@ -95,15 +95,15 @@ totalement différente. Nous n'attendons pas la même chose d'un système boite noire ou boite blanche.

L'axe "Taille du système" décrit à quel niveau (ou altitude) - nous testons : du plus bas, unitaire (une fonction ou une + nous testons : du plus bas, unitaire (une fonction ou une méthode) au plus haut, tout le système, ce qui inclut les composants (ensemble de fonctions) et l'intégration des composants dans d'autres composants, qui, - ensemble, forment le système. Tous les niveaux sont important : ce n'est pas + ensemble, forment le système. Tous les niveaux sont important : ce n'est pas parce qu'une fontion fait ce qu'elle est supposée faire qu'elle s'intégrera correctement avec une autre.

-

Enfin, l'axe "Type de test" décrit l'objectif des tests : +

Enfin, l'axe "Type de test" décrit l'objectif des tests : fonctionnel (“tout fonctionne comme prévu et c'est tout“), robustesse (“il n'est pas possible de mettre le système dans un état d'erreur si nous faisons quelque chose d'imprévu“), @@ -126,22 +126,22 @@ appelés entrées) d'un SUT. Un scénario de test est une paire composée d'un état (le contexte dans lequel est exécuté le test) et un test. Une suite de test est ensemble de scénario de test. Par - conséquent, il y a deux états du point du vue du test : un + conséquent, il y a deux états du point du vue du test : un pré-état — avant l'exécution du SUT — et un post-état — après l'exécution —.

-

Construire le pré-état est critique : le but est de mettre le SUT dans un +

Construire le pré-état est critique : le but est de mettre le SUT dans un (pré-)état spécifique afin de le tester. La partie du scénario de test responsable de créer le pré-état est appelé le préambule. Ainsi, le préambler est le code qui met le SUT dans un état spécifique.

-

Ainsi, en écrivant un scénario de test, nous aurons 3 éléments à considérer :

+

Ainsi, en écrivant un scénario de test, nous aurons 3 éléments à considérer :

    -
  1. Le préambule, pour mettre le SUT dans un état spécifique ;
    2. -
  2. L'exécution, pour exécuter le SUT et obtenir un résultat ;
    3. +
  3. Le préambule, pour mettre le SUT dans un état spécifique ;
    4. +
  4. L'exécution, pour exécuter le SUT et obtenir un résultat  ;
  5. L'oracle, pour évaluer le verdict (basé sur le résultat de l'exécution et le post-état).
-

L'oracle consiste en une séquence d'assertions : “Est-ce que cette valeur - est égale à… ?”, “Est-ce que la valeur a changé de cette façon… ?” etc. Il +

L'oracle consiste en une séquence d'assertions : “Est-ce que cette valeur + est égale à… ?”, “Est-ce que la valeur a changé de cette façon… ?” etc. Il est censé pouvoir vérifier la forme de certaines données mais également comparer des données entre le pré et le post-état.

Dans un scénario de test, nous représentons et introduisons le préambule, @@ -181,19 +181,19 @@

Plusieurs études (articles, journaux et une thèse de doctorat) ont été publiées à propos de Hoa\Test, - Hoa\Praspel et Hoa\Realdom:

+ Hoa\Praspel et Hoa\Realdom :

  • A Constraint Solver for PHP Arrays, présenté à CSTVA 2013 (Luxembourg, Luxembourg), article, présentation et - détails ;
    • + détails ;
  • Grammar-Based Testing using Realistic Domains in PHP, présenté à A-MOST 2012 (Montréal, Canada), article, présentation et - détails ;
    • + détails ;
  • Praspel: A Specification Language for Contract-Driven Testing in PHP, présenté à ICTSS 2011 (Paris, France), article et @@ -219,7 +219,7 @@ classe. Un cas de test est une méthode de cette classe qui exprime le préambule, l'exécution du SUT et l'oracle. Le modèle d'une suite de test est le suivant (supposons la suite de test Test/Unit/Bar.php de la bibliothèque - Hoa\Foo) :

    + Hoa\Foo) :

    namespace Hoa\Foo\Test\Unit;
 
 use Hoa\Foo\Bar as SUT;
@@ -249,7 +249,7 @@ class Bar extends Test\Unit\Suite
   Elles  doivent être préfixées par case_. Un cas de test doit 
   suivre la structure préambule, exécution et oracle, représentés respectivement 
   par les mots clés given, when et then. 
-  Un cas de test doit donc être écrit de la manière suivante :
    
+  Un cas de test doit donc être écrit de la manière suivant  :
    
   
    public function case_classic()
 {
     $this
@@ -269,7 +269,7 @@ class Bar extends Test\Unit\Suite
   des appels de fonction avec une arité non-liée. Ce sont des méthodes vides, 
   elles ne font rien. Le but n'est pas de leur passer quelque chose mais de 
   déclarer des variables pour établir le préambule et exécuter le test. Par 
-  exemple :
     
+  exemple :
     
   
    public function case_sum()
 {
     $this
@@ -284,7 +284,7 @@ class Bar extends Test\Unit\Suite
             ->integer($result)
                 ->isEqualTo(3);
 }
    
-  
    Ceci est strictement équivalent à écrire :
    
+  
    Ceci est strictement équivalent à écrire :
    
   
    public function case_sum()
 {
     // Given:
@@ -297,14 +297,14 @@ class Bar extends Test\Unit\Suite
 }
    
   
    Nous utilisons toutefois la première forme qui est plus claire, l'indentation
   et les mots clés spéciaux (au travers des noms de méthodes) nous forcent à 
-  séparer clairement les 3 parties : préambule, exécution du test et oracle.
    
+  séparer clairement les 3 parties : préambule, exécution du test et oracle.
    
   
    La variable $result est spéciale. Elle 
   doit toujours contenir le résultat de l'exécution du test, 
   i.e. le résultat de la déclaration return 
   du SUT. Ceci est une convention.
     
   
    Un cas de test peut contenir plusieurs exécutions avec des oracles multiples
   (par exemple si un SUT retourne différent résultats en fonction du temps). 
-  Ainsi, le cas de test doit être écrit comme ceci :
    
+  Ainsi, le cas de test doit être écrit comme ceci :
    
   
    public function case_classic()
 {
     $this
@@ -324,7 +324,7 @@ class Bar extends Test\Unit\Suite
   
    Les assertions sont toujours utilisées après la partie then et
   ont la plupart du temps la forme 
   assertion-groupe->assertion. Nous pouvons 
-  également lier des groupes d'assertions. Par exemple :
    
+  également lier des groupes d'assertions. Par exemple :
    
   
    public function case_sum()
 {
     $this
@@ -348,7 +348,7 @@ class Bar extends Test\Unit\Suite
   humaines", il est parfois utile de découvrir qu'une assertion spécifique 
   existe déjà, comme par exemple float->isNearlyEqualTo qui compare 
   2 flottants comme prévu la plupart du temps. N'hésitez pas à consulter la 
-  documentation d'atoum régulièrement !
    
+  documentation d'atoum régulièrement !
    
 
   
    Génération automatique 
   des données de test
    
@@ -366,7 +366,7 @@ class Bar extends Test\Unit\Suite
   sample (à l'interne c'est un handler mais la syntaxe est 
   la même) pour générer une valeur ou sampleMany pour générer 
   plusieurs valeurs. Par exemple, pour générer automatiquement des entiers dans 
-  l'intervalle 7 à 13 ou 42 à 153:
    
+  l'intervalle 7 à 13 ou 42 à 153 :
    
   
    public function case_sum()
 {
     $this
@@ -384,7 +384,7 @@ class Bar extends Test\Unit\Suite
           ->…;
 }
    
   
    Actuellement, atoum/praspel-extension fournit 3 asserters pour 
-  générer des données et 1 asserter pour les valider :
    
+  générer des données et 1 asserter pour les valider :
    
   
      
     
    1. realdom pour créer une disjonction de domaine réaliste 
     (or dans l'exemple précédent),
      2. 
@@ -400,7 +400,7 @@ class Bar extends Test\Unit\Suite
   Ainsi, nous sommes capable de générer automatiquement ou 
   valider une donnée qui correspond à une expression 
   régulière. L'exemple suivant génère une chaîne similaire à une 
-  adresse email :
      
+  adresse email :
      
   
      $this
     ->given(
         $email = $this->sample(
@@ -410,7 +410,7 @@ class Bar extends Test\Unit\Suite
     )
     ->…
      
   
      L'exemple ci-dessous déclare un domaine réaliste qui représente une date 
-  avec le format d/m H:i, entre hier et lundi prochain :
      
+  avec le format d/m H:i, entre hier et lundi prochain :
      
   
      $this
     ->given(
         $_date = $this->realdom->date(
@@ -422,17 +422,17 @@ class Bar extends Test\Unit\Suite
         )
     )
     ->…
      
-  
      Ensuite, pour générer une date :
      
+  
      Ensuite, pour générer une date :
      
   
      $this->sample($_date)
      
-  
      Ou pour en générer 42 :
      
+  
      Ou pour en générer 42 :
      
   
      $this->sampleMany($_date, 42)
      
   
      De la même manière, des booléens, tableaux, classes, couleurs, chaînes basés
-  sur des grammaires etc. peuvent être générées… mais également validés !
+  sur des grammaires etc. peuvent être générées… mais également validés !
   Contrairement à realdom, sample et 
   sampleMany, predicate est un vrai asserter. Par 
-  nature, il calcule un booléen : soit true or 
+  nature, il calcule un booléen : soit true or 
   false. Il peut être utilisé sur une 
-  disjonction de domaine réaliste, par exemple :
      
+  disjonction de domaine réaliste, par exemple :
      
   
      $this
     ->given(
         $_date = $this->realdom->date(
@@ -468,7 +468,7 @@ class Bar extends Test\Unit\Suite
   bibliothèque. Composer est nécessaire
   pour installer ses dépendances, ce qui inclus
   Hoa\Test comme une dépendance de développement. Ainsi, à partir
-  de la racine du dépôt de la bibliothèque:
      
+  de la racine du dépôt de la bibliothèque :
      
   
      $ composer install
      
   
      Par défaut, composer va installer les dépendances de développement. Sinon,
   vous pouvez le forcer en ajoutant l'option --dev.
      
@@ -479,7 +479,7 @@ class Bar extends Test\Unit\Suite
   toutes les sous-commandes disponible pour cette installation. Nous devrions
   voir les commandes de tests. Pour les exécuter, nous allons utiliser la
   sous-commande test:run. Nous devons fournir un répertoire où les
-  tests sont écrits, c'est toujours Test/. Ainsi: 
      
+  tests sont écrits, c'est toujours Test/. Ainsi : 
      
   
      $ vendor/bin/hoa test:run --directories Test/
      
   
      Notez que l'option --directories a une forme plurielle. C'est
   parce que l'on peut spécifier plus d'un répertoire, les noms devant être
@@ -489,11 +489,11 @@ class Bar extends Test\Unit\Suite
   
      Interprété le résultat du test
      
 
   
      Le rapport de test en ligne de commande utilise des couleurs pour indiquer le 
-  verdicte du test: vert pour un succès, rouge pour un échec ou non
-  concluant. Dans le cas d'un succès, nous devrions voir:
      
+  verdicte du test : vert pour un succès, rouge pour un échec ou non
+  concluant. Dans le cas d'un succès, nous devrions voir :
      
 
   
      Success (S tests, c/C methods, V void method, K skipped method, A assertions)!
      
-  
      où:
      
+  
      où :
      
   
        
     
      • S est le nombre de suite de tests,
        • 
     
      • c et C sont les nombres de
@@ -502,7 +502,7 @@ class Bar extends Test\Unit\Suite
     
      • K est le nombre de tests skipped,
        • 
     
      • A est le nombre d'assertions.
        • 
   
      
-  
      Dans le cas d'un échec, nous devrions voir:
      
+  
      Dans le cas d'un échec, nous devrions voir :
      
   
      Failure (S tests, c/C methods, V void method, K skipped method, …, F failure, E error, X exception)!
 > There is F failure:
 …
      
@@ -515,16 +515,16 @@ class Bar extends Test\Unit\Suite
   représentation différentielle textuelle de ce qui est attendue et de ce que
   nous avons.
      
 
-  
      Debugging mode
      
+  
      Mode debug
      
 
-  
      In some cases it is possible that debugging information are accessible but
-  hidden for a regular running. To enable the outputs, we need to use the
-  --debug option; thus:
      
+  
      Dans certains cas, il est possible que certaines informations de debug
+  soient accessibles mais cachées lors d'une exécution des tests classique.
+  Pour activer cette sortie, nous devons utiliser l'option
+  --debug ; Ainsi :
      
   
      $ vendor/bin/hoa test:run --directories Test/ --debug
      
-  
      The order of the option does not matter, as usual with the hoa
-  command.
      
-  
      To produce a debugging information, we should use the dump
-  handler while writing the test case. For instance:
      
+  
      L'ordre des options importe peu, comme toujours avec la commande hoa.
      
+  
      Pour produire les informations de debug, nous devons utiliser l'instruction dump
+  lors de l'écriture de notre cas de test. Par exemple :
      
   
      public function case_sum()
 {
     $this
@@ -695,8 +695,8 @@ var_dump($file->readAll());
 
   
      Pour modifier les permissions, les fonctions d'autorisation de flux
   spécifiques peuvent être utilisées ou nous pouvons les définir directement en
-  utilisant la chaîne de requête de permissions suivie d'une valeur octale;
-  Ainsi:
      
+  utilisant la chaîne de requête de permissions suivie d'une valeur octale ;
+  Ainsi :
      
   
      $file = new Hoa\File\ReadWrite('hoa://Test/Vfs/Foo?permissions=0644');
 var_dump($file->getReadablePermissions());
 
@@ -727,7 +727,7 @@ $file  = new Hoa\File\ReadWrite('hoa://Test/Vfs/Foo?atime=' . $aTime);
      fonctionnels, automatisés ou
   automatiques, soit en boîtes blanches, soit
   en boîtes noires. Elle est plus qu'un wrapper autour d'atoum: Elle fournit une structure de test et de
+  href="http://atoum.org/">atoum : Elle fournit une structure de test et de
   conventions, un système de fichiers virtuel et des
   extensions pour générer automatiquement des
   données de test, générer automatiquement des tests ou d'obtenir un puissant

From bdbf76a0c3f7c032cfc72bcadc14c81f0fbb4bee Mon Sep 17 00:00:00 2001
From: Alexis von Glasow 
Date: Wed, 20 Sep 2017 14:13:13 +0200
Subject: [PATCH 25/28] Translate 'Select tests to run'

---
 Documentation/Fr/Index.xyl | 81 +++++++++++++++++++-------------------
 1 file changed, 40 insertions(+), 41 deletions(-)

diff --git a/Documentation/Fr/Index.xyl b/Documentation/Fr/Index.xyl
index ff039f9..457c82e 100644
--- a/Documentation/Fr/Index.xyl
+++ b/Documentation/Fr/Index.xyl
@@ -541,50 +541,49 @@ class Bar extends Test\Unit\Suite
                 ->isEqualTo(3);
 }
      
 
-  
      Select tests to run
      
-
-  
      Selecting tests to run enables a faster feedback and a
-  shorter “test loop”. We previously saw the
-  --directories option to pick some directories: Either the test
-  root directory Test/ or one or many sub-directories (with
-  --directories Test/Foo/,Test/Bar/,Test/Baz/Qux/ for
-  instance).
      
-  
      We also have the --files option to select one or many
-  specific files to run. For instance:
      
+  
      Sélectionnez les tests à exécuter
      
+
+  
      Sélectionnez les tests à exécuter permet un retour rapide
+  et une plus courte “boucle de test”.  Nous avons vu
+  précédemment l'option --directories pour définir certains
+  répertoires : Soit le répertoire racine Test, soit un ou plusieurs
+  sous-répertoire (avec --directories
+  Test/Foo/,Test/Bar/,Test/Baz/Qux/ par exemple)
      
+  
      Nous avons aussi l'option --files pour sélectionner un ou
+  plusieurs fichiers à exécuter spécifique. Par exemple :
      
   
      $ vendor/bin/hoa test:run --files Test/Unit/Foo.php,Test/Unit/Bar.php
      
-  
      Finally, Hoa\Test requires
-  the
-  atoum/ruler-extension extension to be installed. This
-  extension allows to precisely filter tests to run. We
-  access to it with the --filter option followed by an
-  expression. Fun fact: Expressions are based on
-  the Hoa\Ruler library!
      
-  
      The following variables are available in a filter expression:
      
+  
      Finalement, Hoa\Test nécessite l'installation de l'extension 
+  atoum/ruler-extension. Cette extension permet de
+  filtrer précisément les tests à lancer.  Nous y accédons
+  avec l'option --filter suivie par une expression.
+  Anecdote : Les expressions sont basées sur la bibliothèque Hoa\Ruler!
      
+  
      Les variables suivantes sont disponibles dans l'expression du filtre :
      
   
        
-    
      • method represents the test case name,
        • 
-    
      • class represents the test suite name,
        • 
-    
      • namespace represents the test suite namespace,
        • 
-    
      • tags represents test suite or test case's tags.
        • 
+    
      • method représente le nom du cas de test,
        • 
+    
      • class représente le nom de la suite de test,
        • 
+    
      • namespace représente l'espace de nom de la suite de test,
        • 
+    
      • tags représente la suite de test ou le label du cas de test.
        • 
   
      
-  
      All standard operators from the Hoa\Ruler library can be used.
-  So for instance, to only run the Hoa\Foo\Test\Unit\Bar test
-  suite, which is represented by a class, we will write:
      
+  
      Tous les opérateurs standards de la bibliothèque Hoa\Ruler
+  peuvent être utilisés. Par exemple, pour lancer uniquement la suite de test
+  Hoa\Foo\Test\Unit\Bar qui est représentée par une classe, nous
+  écrirons :
      
   
      $ vendor/bin/hoa test:run --directories Test/ --filter 'class = "Hoa\Foo\Test\Unit\Bar"'
      
-  
      Or, to run only two specific test cases, let's say
-  case_sum and case_baz:
      
+  
      Ou, pour lancer uniquement deux cas de tests spécifiques, supposons
+  case_sum et case_baz :
      
   
      $ vendor/bin/hoa test:run --directories Test/ --filter 'method = "case_sum" or method = "case_baz"'
      
-  
      The previous example is strictly equivalent to:
      
+  
      L'exemple précédent est strictement équivalent à :
      
   
      $ vendor/bin/hoa test:run --directories Test/ --filter 'method in ["case_sum", "case_baz"]'
      
-  
      Another example to filter by test suites' name: Only the ones that end by
-  Qux:
      
+  
      Un autre exemple de filtre pour les suites de tests : Seulement ceux terminant par
+  Qux :
      
   
      $ vendor/bin/hoa test:run --directories Test/ --filter 'class matches "Qux$"'
      
-  
      The matches operator requires a regular expression to
-  the PCRE format.
      
-  
      Finally, test suites and test cases can hold one or more tags, thanks to the
-  @tags annotation. An annotation is a comment of kind /**
-  … */ located on top of a class, interface, method,
-  function etc. Tags allow to have a transversal classification of test cases.
-  For instance:
      
+  
      L'opérateur matches nécessite une expression régulière respectant
+  le format PCRE.
      
+  
      Finalement, les cas de tests et les suites de tests peuvent avoir un ou plusieurs labels, merci à l'annotation
+  @tags. Une annotation est un commentaire du genre /**
+  … */ localisé au dessus d'une classe, interface, méthode,
+  fonction etc. Les labels permettent d'avoir une classification des cas de
+  tests. Par exemple :
      
   
      /**
  * @tags featureA featureB
  */
@@ -592,11 +591,11 @@ public function case_sum()
 {
     // …
 }
      
-  
      To run only test cases with the tag featureA, we will use the
-  following command-line:
      
+  
      Pour lancer uniquement les cas de tests avec le label featureA,
+  nous allons utiliser la ligne de commande suivante :
      
   
      $ vendor/bin/hoa test:run --directories Test/ --filter '"featureA" in tags'
      
-  
      Here, the variable tags contains an array of strings,
-  representing tag names.
      
+  
      Ici, la variable tags contient un tableau de chaines
+  représentant les noms des labels.
      
 
   
      Choose the PHP virtual
   machine
      

From 863fd8e7098f289e9424d2a54560233679375cd1 Mon Sep 17 00:00:00 2001
From: Alexis von Glasow 
Date: Tue, 26 Sep 2017 14:03:48 +0200
Subject: [PATCH 26/28] Translate 'Test execution engine'

---
 Documentation/Fr/Index.xyl | 55 ++++++++++++++++++++------------------
 1 file changed, 29 insertions(+), 26 deletions(-)

diff --git a/Documentation/Fr/Index.xyl b/Documentation/Fr/Index.xyl
index 457c82e..ba5048f 100644
--- a/Documentation/Fr/Index.xyl
+++ b/Documentation/Fr/Index.xyl
@@ -617,36 +617,39 @@ public function case_sum()
   the PHP specification as
   most as possible.
      
 
-  
      Test execution engine
      
+  
      Moteur d'exécution des tests
      
 
-  
      atoum provides several test execution engines, such as:
      
+  
      atoum fournit plusieurs moteurs d'exécution de test, tels que :
      
   
        
-    
      • Inline, one test case after another in the same
-    process,
        • 
-    
      • Isolate, one test case after another but each time in a
-    new process,
        • 
-    
      • Concurrent, “all” test cases at the same time in
-    separated processes.
        • 
+    
      • Inline, un cas de test après un autre dans le même
+    processus,
        • 
+    
      • Isolate, un cas de test après un autre mais à chaque fois
+    dans un nouveau processus,
        • 
+    
      • Concurrent, “tous” les cas de tests en même temps dans des
+    processus séparés.
        • 
   
      
-  
      When running tests, isolation is really important: No memory conflict, no
-  execution conflict, state of the System Under Test is reset each time etc.
-  The test verdict does not depend of a previous run and is therefore
-  deterministic and unambiguous (also if the
-  SUT is).
      
-  
      By default, Hoa\Test will use the concurrent
-  test execution engine. All test cases are not executed at the same time; in
-  fact the number of test cases to run is defined by the number of processes to
-  use. By default, this is either 2 or 4 depending of the platform but we can
-  specify it by using the --concurrent-processes option. Thus, to
-  force using 1024 processes to run tests (assuming we have a monster
-  computer):
      
+  
      Lorsque nous exécutons les tests, l'isolation est vraiment importante :
+  Pas de conflit de mémoire, pas de conflit d'exécution, l'état du SUT est
+  réinitialisé à chaque fois etc.
+  Le verdict du test ne dépend pas de l'exécution précédente et par conséquent
+  déterministe et non ambigu (seulement si le
+  SUT l'est).
      
+  
      Par defaut, Hoa\Test va utiliser le moteur d'exécution de
+  test concurrent. Tous les cas de tests ne snt pas exécuté au
+  même moment ; in en fait le nombre de cas de tests à exécuter sont défini par
+  le nombre de processus utilisés.  Par defaut, c'est soit 2 ou 4 dependant de
+  la platforme mais nous pouvons le spécifier avec l'option
+  --concurrent-processes.
+  Ainsi, pour forcer l'utilisation de 1024 processus pour lancer les tests
+  (supposant que nous ayons un serveur monstre) :
      
   
      $ vendor/bin/hoa test:run --directories Test/ --concurrent-processes 1024
      
-  
      Because the inline test execution engine is not interesting for Hoa's
-  usecases and contexts and because the isolate test execution engine has more
-  cons than pros compared to the concurrent one (mainly the latter is faster
-  than the former), we cannot change the test execution engine. However, to
-  emulate the isolate test engine, we could force
-  --concurrent-processes to 1.
      
+  
      Parce que les tests inline ne sont pas intéressants pour
+  les cas de tests et le contexte de Hoa et parce que l'isolation du moteur
+  d'exécution des tests a plus de contre que de pour comparé au mode concurrent
+  (principalement ce dernier est plus rapide que le premier), nous ne pouvons
+  changer le moteur d'exécution des tests. Cependant, pour simuler le moteur
+  d'exécution isolé, nous pouvons forcer --concurrent-processes à
+  1.
      
 
   
      Virtual file system
      
 

From fba9210a8593d6728138e41722143974cbd37d3a Mon Sep 17 00:00:00 2001
From: Alexis von Glasow 
Date: Tue, 17 Oct 2017 23:29:48 +0200
Subject: [PATCH 27/28] Fix typo

---
 Documentation/Fr/Index.xyl | 30 +++++++++++++++---------------
 1 file changed, 15 insertions(+), 15 deletions(-)

diff --git a/Documentation/Fr/Index.xyl b/Documentation/Fr/Index.xyl
index ba5048f..12ca11d 100644
--- a/Documentation/Fr/Index.xyl
+++ b/Documentation/Fr/Index.xyl
@@ -55,7 +55,7 @@
   test sont calculés par la machine. C'est le rôle des frameworks « xUnit » tel
   que atoum ou
   PHPUnit. L'ingénieur utilisera les frameworks
-  pour écrire des tests et la machine pour les exécuter. Finalement les tests
+  pour écrire des tests et la machine pour les exécuter. Finalement, les tests
   automatiques sont générés et exécutés par la machine.
   La machine peut compter sur une spécification, comme un contrat, pour générer
   automatiquement les tests (s'il vous plaît, allez voir la
@@ -99,8 +99,8 @@
   méthode) au plus haut, tout le système, ce qui inclut les
   composants (ensemble de fonctions) et
   l'intégration des composants dans d'autres composants, qui,
-  ensemble, forment le système. Tous les niveaux sont important : ce n'est pas
-  parce qu'une fontion fait ce qu'elle est supposée faire qu'elle s'intégrera
+  ensemble, forment le système. Tous les niveaux sont importants : ce n'est pas
+  parce qu'une fonction fait ce qu'elle est supposée faire qu'elle s'intégrera
   correctement avec une autre.
      
 
   
      Enfin, l'axe "Type de test" décrit l'objectif des tests :
@@ -126,7 +126,7 @@
   appelés entrées) d'un SUT. Un scénario de test est une paire
   composée d'un état (le contexte dans lequel est exécuté le test) et un test.
   Une suite de test est ensemble de scénario de test. Par
-  conséquent, il y a deux états du point du vue du test : un
+  conséquent, il y a deux états du point de vue du test : un
   pré-état — avant l'exécution du SUT — et un
   post-état — après l'exécution —.
      
   
      Construire le pré-état est critique : le but est de mettre le SUT dans un
@@ -153,14 +153,14 @@
   
      Hoa n'a pas développé son propre framework de tests pour plusieurs raisons.
   La raison principale étant que c'est une tâche laborieuse. Cela implique plus
   de développement, plus d'outils à maintenir, moins de gens concentrés sur Hoa
-  etc. A la place, nous préférons choisir un bon projet sur lequel nous
+  etc. À la place, nous préférons choisir un bon projet sur lequel nous
   appuyer et y contribuer. Nous avons opté pour atoum,
   “un framework de test simple, moderne et intuitif”.
      
   
      Ainsi, la bibliothèque Hoa\Test est la base pour tester toutes
   les bibliothèques de Hoa. Elle intègre atoum et vise à être un pont entre
   les fonctionnalités de Hoa et atoum. Elle ajoute également quelques
-  fonctionnalités si nécessaire. Elle est plus qu'une couche d'abstraction au
-  dessus d'atoum. Hoa\Test fournit également sa propre ligne de
+  fonctionnalités si nécessaire. Elle est plus qu'une couche d'abstraction
+  au-dessus d'atoum. Hoa\Test fournit également sa propre ligne de
   commande pour exécuter les tests avec everything pre-packaged. En conséquence,
   Hoa\Test fournit un environnement de test prêt à l'emploi pour
   Hoa.
      
@@ -518,7 +518,7 @@ class Bar extends Test\Unit\Suite
   
      Mode debug
      
 
   
      Dans certains cas, il est possible que certaines informations de debug
-  soient accessibles mais cachées lors d'une exécution des tests classique.
+  soient accessibles, mais cachées lors d'une exécution des tests classiques.
   Pour activer cette sortie, nous devons utiliser l'option
   --debug ; Ainsi :
      
   
      $ vendor/bin/hoa test:run --directories Test/ --debug
      
@@ -555,7 +555,7 @@ class Bar extends Test\Unit\Suite
   
      Finalement, Hoa\Test nécessite l'installation de l'extension 
   atoum/ruler-extension. Cette extension permet de
   filtrer précisément les tests à lancer.  Nous y accédons
-  avec l'option --filter suivie par une expression.
+  avec l'option --filter suivie d'une expression.
   Anecdote : Les expressions sont basées sur la bibliothèque Hoa\Ruler!
      
   
      Les variables suivantes sont disponibles dans l'expression du filtre :
      
   
        
@@ -581,7 +581,7 @@ class Bar extends Test\Unit\Suite
   le format PCRE.
        
   
        Finalement, les cas de tests et les suites de tests peuvent avoir un ou plusieurs labels, merci à l'annotation
   @tags. Une annotation est un commentaire du genre /**
-  … */ localisé au dessus d'une classe, interface, méthode,
+  … */ localisé au-dessus d'une classe, interface, méthode,
   fonction etc. Les labels permettent d'avoir une classification des cas de
   tests. Par exemple :
        
   
        /**
@@ -623,7 +623,7 @@ public function case_sum()
   
          
     
        • Inline, un cas de test après un autre dans le même
     processus,
          • 
-    
        • Isolate, un cas de test après un autre mais à chaque fois
+    
        • Isolate, un cas de test après un autre, mais à chaque fois
     dans un nouveau processus,
          • 
     
        • Concurrent, “tous” les cas de tests en même temps dans des
     processus séparés.
          • 
@@ -636,16 +636,16 @@ public function case_sum()
   SUT l'est).
          
   
          Par defaut, Hoa\Test va utiliser le moteur d'exécution de
   test concurrent. Tous les cas de tests ne snt pas exécuté au
-  même moment ; in en fait le nombre de cas de tests à exécuter sont défini par
-  le nombre de processus utilisés.  Par defaut, c'est soit 2 ou 4 dependant de
-  la platforme mais nous pouvons le spécifier avec l'option
+  même moment ; en fait, le nombre de cas de tests à exécuter sont définis par
+  le nombre de processus utilisés.  Par defaut, c'est soit 2 ou 4 dépendant de
+  la platforme, mais nous pouvons le spécifier avec l'option
   --concurrent-processes.
   Ainsi, pour forcer l'utilisation de 1024 processus pour lancer les tests
   (supposant que nous ayons un serveur monstre) :
          
   
          $ vendor/bin/hoa test:run --directories Test/ --concurrent-processes 1024
          
   
          Parce que les tests inline ne sont pas intéressants pour
   les cas de tests et le contexte de Hoa et parce que l'isolation du moteur
-  d'exécution des tests a plus de contre que de pour comparé au mode concurrent
+  d'exécution des tests a plus de contre que de pour comparer au mode concurrent
   (principalement ce dernier est plus rapide que le premier), nous ne pouvons
   changer le moteur d'exécution des tests. Cependant, pour simuler le moteur
   d'exécution isolé, nous pouvons forcer --concurrent-processes à

From 993e7314f80d2d7a89624e6092ba5d2c28c1ccb3 Mon Sep 17 00:00:00 2001
From: Alexis von Glasow 
Date: Thu, 26 Oct 2017 16:44:01 +0200
Subject: [PATCH 28/28] Translate 'Choose PHP virtual machine'

---
 Documentation/Fr/Index.xyl | 35 ++++++++++++++++++-----------------
 1 file changed, 18 insertions(+), 17 deletions(-)

diff --git a/Documentation/Fr/Index.xyl b/Documentation/Fr/Index.xyl
index 12ca11d..56dc9ac 100644
--- a/Documentation/Fr/Index.xyl
+++ b/Documentation/Fr/Index.xyl
@@ -597,25 +597,26 @@ public function case_sum()
   
          Ici, la variable tags contient un tableau de chaines
   représentant les noms des labels.
          
 
-  
          Choose the PHP virtual
-  machine
          
-
-  
          When testing, this is also useful to be able to select one specific
-  PHP virtual machine, like a
-  specific version of PHP (the default virtual machine) or
-  the latest version of HHVM for instance. There
-  is several PHP virtual machines nowadays and we cannot ignore them.
          
-  
          We select a virtual machine by using the
-  --php-binary option and by providing a path to the virtual CLI
-  binary; thus, for instance:
          
+  
          Choisir la machine
+  virtuelle PHP
          
+
+  
          Lors de test, il est aussi utile de pouvoir choisir une machine
+  virtuelle PHP spécifique, comme une
+  version spécifique de PHP (la machine virtuelle par défaut) ou
+  la dernière version de HHVM par exemple. Il y
+  a plusieurs machine virtuelle PHP de nos jours et nous ne pouvons les
+  ignorer.
          
+  
          Nous choisissons la machine virtuelle en utilisant l'option
+  --php-binary et e fournissant le chemin vers le binaire ;
+  par exemple:
          
   
          $ vendor/bin/hoa test:run --directories … --php-binary /usr/bin/php
          
-  
          We can imagine the --php-binary option value defined by a
-  global variable. Thus, we could re-use the same script to execute tests
-  against several PHP virtual machines, like:
          
+  
          Nous pouvons imaginer la valeur de l'option --php-binary
+  définie par une variable globale. Ainsi, nous pouvons réutiliser le même
+  script pour exécuter les tests avec plusieurs machines virtuelles, comme :
          
   
          $ PHP_BIN=/usr/bin/php vendor/bin/hoa test:run --directories … --php-binary $PHP_BIN
          
-  
          Please, remember to use PHP syntax and features described in
-  the PHP specification as
-  most as possible.
          
+  
          Il est conseillé d'utiliser le plus possible la syntaxe PHP et les
+  fonctionnalités décrites dans les spécifications PHP
          
 
   
          Moteur d'exécution des tests