mirror of
https://github.com/pgbackrest/pgbackrest.git
synced 2025-02-19 19:44:38 +02:00
Update contributing documentation and remove test/README.md.
When the Vagrant file was updated to use pgbackrest/ vs /backrest/ as the location for executing tests and building the documentation, parts of the contributing.xml (and hence the CONTRIBUTING.md) were not updated since some parts of the document are not actually executed when the CONTRIBUTING.md is built from contributing.xml: those parts that are executed were updated but those parts that are not executed were not. This commit fixes the contributing.xml issue but also removes test/README.md as its contents were out of date and redundant given that they are covered in CONTRIBUTING.md.
This commit is contained in:
Cynthia Shang
David Steele
parent
55c3a3c8d3
commit
63b9f46a34
@ -235,7 +235,7 @@ To add an option, add the following to the `<option-list>` section; if it does n
|
||||
|
||||
For testing, it is recommended that Vagrant and Docker be used; instructions are provided in the `README.md` file of the pgBackRest [test](https://github.com/pgbackrest/pgbackrest/blob/master/test) directory. A list of all possible test combinations can be viewed by running:
|
||||
```
|
||||
/backrest/test/test.pl --dry-run
|
||||
pgbackrest/test/test.pl --dry-run
|
||||
```
|
||||
> **WARNING:** currently the `BACKREST_USER` in `ContainerTest.pm` must exist, or the test suite will fail with a string concatenation error.
|
||||
|
||||
@ -243,11 +243,11 @@ If using a RHEL system, the CPAN XML parser is required for running `test.pl` an
|
||||
|
||||
While some files are automatically generated during `make`, others are generated by running the test harness as follows:
|
||||
```
|
||||
/backrest/test/test.pl --gen-only
|
||||
pgbackrest/test/test.pl --gen-only
|
||||
```
|
||||
Prior to any submission, the html version of the documentation should also be run.
|
||||
```
|
||||
/backrest/doc/doc.pl --out=html
|
||||
pgbackrest/doc/doc.pl --out=html
|
||||
```
|
||||
> **NOTE:** `ERROR: [028]` regarding cache is invalid is OK; it just means there have been changes and the documentation will be built from scratch. In this case, be patient as the build could take 20 minutes or more depending on your system.
|
||||
|
||||
@ -332,12 +332,11 @@ harnessLogResult(
|
||||
|
||||
Unit tests are run, and coverage of the code being tested is provided, by running the following. This example would run the test set from the **define.yaml** section detailed above.
|
||||
```
|
||||
/backrest/test/test.pl --vm-out --dev --module=command --test=check --coverage-only
|
||||
pgbackrest/test/test.pl --vm-out --dev --module=command --test=check --coverage-only
|
||||
```
|
||||
Because no test run is specified and `--coverage-only` has been requested, a coverage report will be generated and written to the local file system under the pgBackRest directory `test/result/coverage` (or `test/coverage` prior to version 2.25) and will highlight code that has not been tested.
|
||||
|
||||
Sometimes it is useful to look at files that were generated during the test. The default for running any test is that, at the start/end of the test, the test harness will clean up all files and directories created. To override this behavior, a single test run must be specified and the option `--no-cleanup` provided. Again, continuing with the check command, we see in **define.yaml** above that there are two tests. Below, test one will be run and nothing will be cleaned up so that the files and directories in test/test-0 can be inspected.
|
||||
```
|
||||
/backrest/test/test.pl --vm-out --dev --module=command --test=check --coverage-only --run=1 --no-cleanup
|
||||
pgbackrest/test/test.pl --vm-out --dev --module=command --test=check --coverage-only --run=1 --no-cleanup
|
||||
```
|
||||
For more details on running tests, again, please refer to the `README.md` file of the pgBackRest [test](https://github.com/pgbackrest/pgbackrest/blob/master/test) directory.
|
||||
|
||||
@ -264,7 +264,7 @@
|
||||
|
||||
<p>For testing, it is recommended that Vagrant and Docker be used; instructions are provided in the <file>README.md</file> file of the <backrest/> <link url="{[github-url-master]}/test">test</link> directory. A list of all possible test combinations can be viewed by running:</p>
|
||||
<code-block>
|
||||
/backrest/test/test.pl --dry-run
|
||||
pgbackrest/test/test.pl --dry-run
|
||||
</code-block>
|
||||
|
||||
<admonition type="warning">currently the <id>BACKREST_USER</id> in <file>ContainerTest.pm</file> must exist, or the test suite will fail with a string concatenation error.</admonition>
|
||||
@ -274,13 +274,13 @@
|
||||
<p>While some files are automatically generated during <code>make</code>, others are generated by running the test harness as follows:</p>
|
||||
|
||||
<code-block>
|
||||
/backrest/test/test.pl --gen-only
|
||||
pgbackrest/test/test.pl --gen-only
|
||||
</code-block>
|
||||
|
||||
<p>Prior to any submission, the html version of the documentation should also be run.</p>
|
||||
|
||||
<code-block>
|
||||
/backrest/doc/doc.pl --out=html
|
||||
pgbackrest/doc/doc.pl --out=html
|
||||
</code-block>
|
||||
|
||||
<admonition type="note"><code>ERROR: [028]</code> regarding cache is invalid is OK; it just means there have been changes and the documentation will be built from scratch. In this case, be patient as the build could take 20 minutes or more depending on your system.</admonition>
|
||||
@ -377,7 +377,7 @@ harnessLogResult(
|
||||
<p>Unit tests are run, and coverage of the code being tested is provided, by running the following. This example would run the test set from the <b>define.yaml</b> section detailed above.</p>
|
||||
|
||||
<code-block>
|
||||
/backrest/test/test.pl --vm-out --dev --module=command --test=check --coverage-only
|
||||
pgbackrest/test/test.pl --vm-out --dev --module=command --test=check --coverage-only
|
||||
</code-block>
|
||||
|
||||
<p>Because no test run is specified and <code>--coverage-only</code> has been requested, a coverage report will be generated and written to the local file system under the <backrest/> directory <file>test/result/coverage</file> (or <file>test/coverage</file> prior to version 2.25) and will highlight code that has not been tested.</p>
|
||||
@ -385,10 +385,8 @@ harnessLogResult(
|
||||
<p>Sometimes it is useful to look at files that were generated during the test. The default for running any test is that, at the start/end of the test, the test harness will clean up all files and directories created. To override this behavior, a single test run must be specified and the option <code>--no-cleanup</code> provided. Again, continuing with the check command, we see in <b>define.yaml</b> above that there are two tests. Below, test one will be run and nothing will be cleaned up so that the files and directories in test/test-0 can be inspected.</p>
|
||||
|
||||
<code-block>
|
||||
/backrest/test/test.pl --vm-out --dev --module=command --test=check --coverage-only --run=1 --no-cleanup
|
||||
pgbackrest/test/test.pl --vm-out --dev --module=command --test=check --coverage-only --run=1 --no-cleanup
|
||||
</code-block>
|
||||
|
||||
<p> For more details on running tests, again, please refer to the <file>README.md</file> file of the <backrest/> <link url="{[github-url-master]}/test">test</link> directory.</p>
|
||||
</section>
|
||||
</section>
|
||||
</doc>
|
||||
|
||||
@ -1,57 +0,0 @@
|
||||
# pgBackRest <br/> Regression, Unit, & Integration Testing
|
||||
|
||||
## Introduction
|
||||
|
||||
pgBackRest uses Docker to run tests and generate documentation. Docker's light-weight virtualization provides the a good balance between proper OS emulation and performance (especially startup)
|
||||
|
||||
A `Vagrantfile` is provided that contains the complete configuration required to run pgBackRest tests and build documentation. If Vagrant is not suitable then the `Vagrantfile` still contains the configuration steps required to build a test system.
|
||||
> **NOTE:** this is not required for normal operation of pgBackRest.
|
||||
|
||||
## Testing
|
||||
|
||||
The easiest way to start testing pgBackRest is with the included `Vagrantfile`.
|
||||
|
||||
_Build Vagrant and Logon_:
|
||||
```
|
||||
cd test
|
||||
vagrant up
|
||||
vagrant ssh
|
||||
```
|
||||
The `vagrant up` command may take some time as a number of Docker containers must also be built. The `vagrant ssh` command automatically logs onto the VM.
|
||||
|
||||
_Run All Tests_:
|
||||
```
|
||||
/backrest/test/test.pl
|
||||
```
|
||||
_Run Tests for a Specific OS_:
|
||||
```
|
||||
/backrest/test/test.pl --vm=co6
|
||||
```
|
||||
_Run Tests for a Specific OS and Module_:
|
||||
```
|
||||
/backrest/test/test.pl --vm=co6 --module=backup
|
||||
```
|
||||
_Run Tests for a Specific OS, Module, and Test_:
|
||||
```
|
||||
/backrest/test/test.pl --vm=co6 --module=backup --test=full
|
||||
```
|
||||
_Run Tests for a Specific OS, Module, Test, and Run_:
|
||||
```
|
||||
/backrest/test/test.pl --vm=co6 --module=backup --test=full --run=1
|
||||
```
|
||||
_Run Tests for a Specific OS, Module, Test, and Process Max_:
|
||||
```
|
||||
/backrest/test/test.pl --vm=co6 --module=backup --test=full --process-max=4
|
||||
```
|
||||
> **NOTE:** process-max is only applicable to the `synthetic` and `full` tests in the `backup` module.
|
||||
|
||||
_Run Tests for a Specific OS, Module, Test, Process Max, and Database Version_:
|
||||
```
|
||||
/backrest/test/test.pl --vm=co6 --module=backup --test=full --process-max=4 --pg-version=9.4
|
||||
```
|
||||
> **NOTE:** pg-version is only applicable to the `full` test in the `backup` module.
|
||||
|
||||
_Iterate All Possible Test Combinations_:
|
||||
```
|
||||
/backrest/test/test.pl --dry-run
|
||||
```
|
||||
Loading…
x
Reference in New Issue
Block a user