Add Setup script for test script symlinks, and README; remove test scripts.
[matthijs/upstream/blosxom.git] / t / README
1 Running Tests
2 =============
3
4   perl ./Setup
5   prove *.t
6
7
8
9 Test Layout
10 ===========
11
12 To add a new test, you want to add two things - a test script (which
13 is typically just a symlink to the main 'driver' script), and a test
14 directory. If you just want a symlink test script, then add your
15 test script name to 'driver_tests', and rerun Setup. To add a new
16 test directory, you're probably best just to copy one of the 
17 existing ones - 'templates' is a good choice:
18
19   cp -rp templates newtest
20
21 Test directory layout is as follows, using 'templates' as an example:
22
23   templates
24   |-- config
25   |   `-- blosxom.conf
26   |-- data
27   |   |-- 1.txt
28   |   |-- 1.txt.200607192254
29   |   |-- content_type.html
30   |   |-- date.html
31   |   |-- foot.html
32   |   |-- head.html
33   |   `-- story.html
34   |-- expected.html
35   `-- spec.yaml
36
37 The 'config' directory contains the config files for this blosxom
38 instance, which is minimally a 'blosxom.conf' file with the $data_dir
39 variable pointing to the 'data' directory. Customising this is 
40 optional.
41
42 The 'data directory' is the set of stories or posts you want to use
43 for your test, and any flavour files you want. Stories may optionally be 
44 suffixed with a numeric timestamp (format YYYYMMDDHHMI) like the 
45 '1.txt.200607192254' entry above, which is used to set the modify time
46 of the story explicitly (since CVS does not store mtimes). Providing 
47 flavour files is recommended so that your tests don't break if the 
48 default flavours change. 
49  
50 At the top level of the test directory are a set of one or more
51 expected output files, and the spec.yaml files which controls the set
52 of tests that are run. For templates, the spec.yaml looks like this:
53
54   tests:
55     - 
56       - ""
57       - expected.html
58
59 This lists the set of tests to be run (in this case just a single test).
60 Each test requires a list of two arguments - the arguments to path to
61 blosxom.cgi (in this case none, an empty string), and a file containing
62 the expected output. So this test will execute blosxom.cgi with no 
63 arguments, and compare the output produced against that contained in
64 the 'expected.html' file.
65
66 A longer spec.yaml example is:
67
68   tests:
69     - 
70       - ""
71       - expected.html
72     -
73       - path=/foo
74       - expected.html
75     -
76       - path=/foo/bar.html
77       - expected.bar
78
79 This defines three tests, one with no arguments, one with a path of 
80 /foo, and a third with a path of /foo/bar.html.
81