Skip to content

HTTPS clone URL

Subversion checkout URL

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