Merge branch 'so/prompt-command'
[git] / contrib / mw-to-git / t / README
1 Tests for Mediawiki-to-Git
2 ==========================
3
4 Introduction
5 ------------
6 This manual describes how to install the git-remote-mediawiki test
7 environment on a machine with git installed on it.
8
9 Prerequisite
10 ------------
11
12 In order to run this test environment correctly, you will need to
13 install the following packages (Debian/Ubuntu names, may need to be
14 adapted for another distribution):
15
16 * lighttpd
17 * php5
18 * php5-cgi
19 * php5-cli
20 * php5-curl
21 * php5-sqlite
22
23 Principles and Technical Choices
24 --------------------------------
25
26 The test environment makes it easy to install and manipulate one or
27 several MediaWiki instances. To allow developers to run the testsuite
28 easily, the environment does not require root priviledge (except to
29 install the required packages if needed). It starts a webserver
30 instance on the user's account (using lighttpd greatly helps for
31 that), and does not need a separate database daemon (thanks to the use
32 of sqlite).
33
34 Run the test environment
35 ------------------------
36
37 Install a new wiki
38 ~~~~~~~~~~~~~~~~~~
39
40 Once you have all the prerequisite, you need to install a MediaWiki
41 instance on your machine. If you already have one, it is still
42 strongly recommended to install one with the script provided. Here's
43 how to work it:
44
45 a. change directory to contrib/mw-to-git/t/
46 b. if needed, edit test.config to choose your installation parameters
47 c. run `./install-wiki.sh install`
48 d. check on your favourite web browser if your wiki is correctly
49    installed.
50
51 Remove an existing wiki
52 ~~~~~~~~~~~~~~~~~~~~~~~
53
54 Edit the file test.config to fit the wiki you want to delete, and then
55 execute the command `./install-wiki.sh delete` from the
56 contrib/mw-to-git/t directory.
57
58 Run the existing tests
59 ~~~~~~~~~~~~~~~~~~~~~~
60
61 The provided tests are currently in the `contrib/mw-to-git/t` directory.
62 The files are all the t936[0-9]-*.sh shell scripts.
63
64 a. Run all tests:
65 To do so, run "make test" from the contrib/mw-to-git/ directory.
66
67 b. Run a specific test:
68 To run a given test <test_name>, run ./<test_name> from the
69 contrib/mw-to-git/t directory.
70
71 How to create new tests
72 -----------------------
73
74 Available functions
75 ~~~~~~~~~~~~~~~~~~~
76
77 The test environment of git-remote-mediawiki provides some functions
78 useful to test its behaviour. for more details about the functions'
79 parameters, please refer to the `test-gitmw-lib.sh` and
80 `test-gitmw.pl` files.
81
82 ** `test_check_wiki_precond`:
83 Check if the tests must be skipped or not. Please use this function
84 at the beggining of each new test file.
85
86 ** `wiki_getpage`:
87 Fetch a given page from the wiki and puts its content in the
88 directory in parameter.
89
90 ** `wiki_delete_page`:
91 Delete a given page from the wiki.
92
93 ** `wiki_edit_page`:
94 Create or modify a given page in the wiki. You can specify several
95 parameters like a summary for the page edition, or add the page to a
96 given category.
97 See test-gitmw.pl for more details.
98
99 ** `wiki_getallpage`:
100 Fetch all pages from the wiki into a given directory. The directory
101 is created if it does not exists.
102
103 ** `test_diff_directories`:
104 Compare the content of two directories. The content must be the same.
105 Use this function to compare the content of a git directory and a wiki
106 one created by wiki_getallpage.
107
108 ** `test_contains_N_files`:
109 Check if the given directory contains a given number of file.
110
111 ** `wiki_page_exists`:
112 Tests if a given page exists on the wiki.
113
114 ** `wiki_reset`:
115 Reset the wiki, i.e. flush the database. Use this function at the
116 begining of each new test, except if the test re-uses the same wiki
117 (and history) as the previous test.
118
119 How to write a new test
120 ~~~~~~~~~~~~~~~~~~~~~~~
121
122 Please, follow the standards given by git. See git/t/README.
123 New file should be named as t936[0-9]-*.sh.
124 Be sure to reset your wiki regulary with the function `wiki_reset`.