Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

Initial commit of a readme for developers

  • Loading branch information...
commit fd434c402f20f882e870e22b25da4072a2349403 1 parent 11a8bc5
Hannes Magnusson authored derickr committed

Showing 1 changed file with 104 additions and 0 deletions. Show diff stats Hide diff stats

  1. 104  README.DEVELOPER.md
104  README.DEVELOPER.md
Source Rendered
... ...
@@ -0,0 +1,104 @@
  1
+## Do you want to contribute?
  2
+
  3
+This is a README for developers wanting to contribute to the MongoDB PHP driver.
  4
+
  5
+
  6
+## Current branches
  7
+
  8
+* 1.2 is the current release branch/stable branch (bugfix only)
  9
+* master is the development branch for new features (to become 1.3)
  10
+
  11
+
  12
+## Github
  13
+
  14
+The official repository of this driver is on [Github](http://www.github.com/mongodb/mongo-php-driver/).
  15
+When fixing a bug in the current release branch, please ensure you branch from it, and submit the Pull Request
  16
+against it again.
  17
+If there has been a while since you update your local fork, please ensure you rebase it properly :)
  18
+
  19
+Bugfixes and Pull Requests should be filed against the *lowest release branch*
  20
+All *new* development happens in master (i.e. new features, BC changes, ..).
  21
+
  22
+
  23
+## Running the tests
  24
+
  25
+To execute the "tests/generic/" tests in a specific mongod environment you can export
  26
+`MONGO_SERVER` environment variable to overwrite the default environment (standalone):
  27
+
  28
+    MONGO_SERVER=REPLICASET-auth php run-tests.php tests/generic/mongo-listdbs-001.phpt
  29
+
  30
+If you export the variable, remember to unset it later - otherwise the test suite may not
  31
+be executed correctly in the environment you expect it too.
  32
+
  33
+
  34
+## Writing tests
  35
+
  36
+The tests/utils.inc file has several helper functions to ease running the same test case
  37
+in several different environment at once (i.e. via 'make tests').
  38
+
  39
+Testscases in the generic/ folder are executed in all configured environments
  40
+(see tests/mongo-test-cfg.inc), the testcases in the replicaset/ folder only when replicaset
  41
+environment is available, the testcases in standalone-auth/ only in Standalone (with auth enabled)
  42
+environment and so on and on.
  43
+
  44
+The most important helper function is the mongo() function, which out of the box will return a Mongo
  45
+object configured for the current environment.
  46
+
  47
+When writing testcases for the Mongo construct, using the helper function won't give you much as it
  48
+abstracts the logic of connecting to servers and doesn't provide a whole lot of room for custom options.
  49
+This is however easily achieved by using the other helper functions such as hostname(), port(),
  50
+username() etc etc. These will return back the configured values for the currently being executed environment.
  51
+
  52
+If you need to do the same "trick" over and over again in a testcase, it is probably worth writing a helper
  53
+function for it in tests/utils.inc.
  54
+
  55
+
  56
+## Test template
  57
+    --TEST--
  58
+    Test for PHP-XYZ: The ticket title
  59
+    --SKIPIF--
  60
+    <?php /* Minimum mongod requirement $needs = "2.2.0"; */ ?>
  61
+    <?php require dirname(__FILE__) ."/skipif.inc"; ?>
  62
+    --FILE--
  63
+    <?php
  64
+    $cn = "PHP-XYZ";
  65
+    require_once dirname(__FILE__) . "/../utils.inc";
  66
+
  67
+    $m = mongo();
  68
+    $c = $m->selectCollection(dbname(), $cn);
  69
+
  70
+    /** Write your test code here **/
  71
+    ?>
  72
+    ===DONE===
  73
+    <?php exit(0); ?>
  74
+    --CLEAN--
  75
+    <?php $c = "PHP-XYZ"; require dirname(__FILE__) ."/clean.inc"; ?>
  76
+    --EXPECTF--
  77
+    ** Expected output here **
  78
+    ===DONE===
  79
+
  80
+Some notes about the template:
  81
+* The dirname() is for PHP 5.2 compatibility.
  82
+* Setting the $needs variable verifies minimum mongod requirements
  83
+* skipif.inc checks if the extension is loaded and general sanity
  84
+* utils.inc is `require_once` as skipif.inc requires that file too
  85
+* If $cn is set, that collection in the dbname() database will be dropped before the test runs
  86
+* mongo() will return a connected Mongo object according to the envrionment or test folder
  87
+* Please use a collection named after the ticket number (for easier tracking)
  88
+* The exit(0); statement allows you to run the testcase standalone from
  89
+  the command line (without running it via run-tests.php) and see what is going on
  90
+  without being flooded with hundred of lines from the --EXPECTF-- section.
  91
+* The --CLEAN-- section is to drop the collection name assigned to $cn 
  92
+
  93
+
  94
+## Code coverage
  95
+
  96
+Code coverage is generated by running the test suite after having enabled coverage before compiling the driver
  97
+
  98
+    $ phpize
  99
+    $ ./configure --enable-coverage
  100
+    $ make clean all tests
  101
+
  102
+Then you should have a coverage/ folder with the juicy details.
  103
+
  104
+

0 notes on commit fd434c4

Please sign in to comment.
Something went wrong with that request. Please try again.