This fork of the original PrivateBin of Sebsauvage was refactored into an object oriented MVC structure. The `index.php` only loads an autoloader (`lib/auto.php`) and starts the application by instancing a `privatebin` object.
## Code Style
# Code Style
To make it easy for you to adopt our code style, we provide you some configuration files for different tools. You just have to install the necessary tools in your IDE and they should use our configuration files automatically.
The main code or **controller** is found in `lib/PrivateBin.php`.
@ -22,38 +22,33 @@ Any option that not every server administrator might want to use or provide shou
More details can be found in the [API documentation](https://zerobin.dssr.ch/documentation/).
## Unit Tests
# Unit Tests
### PHP
## PHP
For unit tests of the php code the folder `tst/` can be used. Apart from helping to implement new features correctly it helps to keep regressions at bay. By default a code coverage report is generated after phpunit is run, the one of the latest release is [publicly](https://codeclimate.com/github/PrivateBin/PrivateBin/coverage) [available](https://www.codacy.com/app/PrivateBin/PrivateBin/files).
In order to run these tests, you will need to install the following packages
and their dependencies:
* phpunit
* php-gd
* php-sqlite3
* php-xdebug (for code coverage reports)
In order to run these tests, you will need to install the following packages and their dependencies:
To run the tests, change into the `tst` directory and run phpunit:
```console
$ cd PrivateBin/tst
$ phpunit
```
Additionally there is the `ConfigurationTestGenerator`. Based on the
configurations defined in its constructor, it generates the unit test file
`tst/ConfigurationCombinationsTest.php`, containing all possible combinations
of these configurations and tests for (most of the) valid combinations. Some of
combinations can't be tested with this method, i.e. a valid option combined with
an invalid one. Other very specific test cases (i.e. to trigger multiple errors)
are covered in `tst/PrivateBinTest.php`. Here is how to generate the
configuration test and run it:
Additionally there is the `ConfigurationTestGenerator`. Based on the configurations defined in its constructor, it generates the unit test file `tst/ConfigurationCombinationsTest.php`, containing all possible combinations of these configurations and tests for (most of the) valid combinations. Some of combinations can't be tested with this method, i.e. a valid option combined with an invalid one. Other very specific test cases (i.e. to trigger multiple errors) are covered in `tst/PrivateBinTest.php`. Here is how to generate the configuration test and run it:
Note that it can take an hour or longer to run the several thousand tests.
### JavaScript
## JavaScript
For unit tests of the JS code the folder `js/` can be used. Apart from helping to implement new features correctly it helps to keep regressions at bay. By default a code coverage report is generated after istanbul is run.
In order to run these tests, you will need to install the following packages
and its dependencies:
* npm
In order to run these tests, you will need to install the following packages and its dependencies:
Then you can use the node package manager to install the latest stable release
of mocha and istanbul (for code coverage reports) globally and jsVerify, jsdom
and jsdom-global locally:
- npm
Then you can use the node package manager to install the latest stable release of mocha and istanbul (for code coverage reports) globally and jsVerify, jsdom and jsdom-global locally:
```console
$ npm install -g mocha istanbul
@ -81,8 +74,8 @@ $ cd PrivateBin/js
$ npm install jsverify jsdom jsdom-global
```
Example for Debian and Ubuntu, including steps to allow current user to install
node modules globally:
Example for Debian and Ubuntu, including steps to allow current user to install node modules globally:
To run the tests, just change into the `js` directory and run istanbul:
```console
$ cd PrivateBin/js
$ istanbul cover _mocha
```
#### Property based unit testing
### Property based unit testing
In the JavaScript unit tests we use the JSVerify library to leverage property
based unit testing. Instead of artificially creating specific test cases to
cover all relevant paths of the tested code (with the generated coverage reports
providing means to check the tested paths), property based testing allows us to
describe the patterns of data that are valid input.
In the JavaScript unit tests we use the JSVerify library to leverage property based unit testing. Instead of artificially creating specific test cases to cover all relevant paths of the tested code (with the generated coverage reports providing means to check the tested paths), property based testing allows us to describe the patterns of data that are valid input.
With each run of the tests, for each `jsc.property` 100 random inputs are
generated and tested. For example we tell the test to generate random strings,
which will include empty strings, numeric strings, long strings, unicode
sequences, etc. This is great for finding corner cases that one might not think
of when explicitly writing one test case at a time.
With each run of the tests, for each `jsc.property` 100 random inputs are generated and tested. For example we tell the test to generate random strings, which will include empty strings, numeric strings, long strings, unicode sequences, etc. This is great for finding corner cases that one might not think of when explicitly writing one test case at a time.
There is another benefit, too: When an error is found, JSVerify will try to find
the smallest, still failing test case for you and print this out including the
associated random number generator (RNG) state, so you can reproduce it easily:
There is another benefit, too: When an error is found, JSVerify will try to find the smallest, still failing test case for you and print this out including the associated random number generator (RNG) state, so you can reproduce it easily:
```console
[...]
@ -124,56 +108,61 @@ associated random number generator (RNG) state, so you can reproduce it easily:
1 failing
1) Helper getCookie returns the requested cookie:
Error: Failed after 30 tests and 11 shrinks. rngState: 88caf85079d32e416b; Counterexample: ["{", "9", "9", "YD8%fT"]; [" ", "_|K:"];
Error: Failed after 30 tests and 11 shrinks. rngState: 88caf85079d32e416b; Counterexample: ["{", "9", "9", "YD8%fT"]; [" ", "_|K:"];
[...]
```
Of course it may just be that you need to adjust a test case if the random
pattern generated is ambiguous. In the above example the cookie string would
contain two identical keys "9", something that may not be valid, but that our
code could encounter and needs to be able to handle.
Of course it may just be that you need to adjust a test case if the random pattern generated is ambiguous. In the above example the cookie string would contain two identical keys "9", something that may not be valid, but that our code could encounter and needs to be able to handle.
After you adjusted the code of the library or the test you can rerun the test
with the same RNG state as follows:
After you adjusted the code of the library or the test you can rerun the test with the same RNG state as follows:
```console
$ istanbul cover _mocha -- test.js --jsverifyRngState 88caf85079d32e416b
```
## Data Model
# Creating new config options
1. Add your config option to `cfg/conf.sample.php`.
2. Add the default value for that config option to `lib/Configuration.php` in the `$_defaults` array.
3. If you want to use the config option in a template, you have to add it to the `_view` function in `lib/PrivateBin.php`. You can then just use the variable in the template file to conditionally include or exclude HTML code.
4. If you want to use it in other parts of the PHP code, you can usually query the config option via the `getKey` method of the `Configuration` object.
A good example of a change, where an option was added is [this one](https://github.com/PrivateBin/PrivateBin/commit/f54036976a486d3f7c83e52fd37ea357fd4e7a62).
# Data Model
If you want to create your own data models, you might want to know how the arrays, that you have to store, look like:
Note that the `.gitignore` will exclude all non-PHP files in the vendor dir when you create a commit.
## Subresource Integrity for Javascript resources
# Subresource Integrity for Javascript resources
Because we implemented [Subresource Integrity (SRI)](https://www.w3.org/TR/SRI/) the SRI hashes in the templates need to be regenerated after each change of a javascript file. To make this easy, we implemented a mechanism for this into the unit testing bootstrap process. After changing any javascript file, follow this process:
* edit the javascript file(s)
* run the unit tests as described above
* deploy the updated javascript file(s) _and_ the updated templates on your webserver
Of course you also manually adjust the hashes in the template files. For more information how to do this [have a look at this article](https://scotthelme.co.uk/subresource-integrity/).
- edit the javascript file(s)
- run the unit tests as described above
- deploy the updated javascript file(s) _and_ the updated templates on your webserver
Of course you also manually adjust the hashes in the template files. For more information how to do this [have a look at this article](https://scotthelme.co.uk/subresource-integrity/).
rugk
7 years ago