tagging: Make sure the related stories output is properly HTML escaped.
[matthijs/upstream/blosxom-plugins.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 'Tests', and rerun Setup. To add a new test 
16 directory, you're probably best just to copy one of the existing 
17 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
35   |   |-- index.html
36   |   `-- index.rss
37   `-- spec.yaml
38
39 The 'config' directory contains the config files for this blosxom
40 instance, which is minimally a 'blosxom.conf' file with the $data_dir
41 variable pointing to the 'data' directory. Customising this is 
42 optional.
43
44 The 'data directory' is the set of stories or posts you want to use
45 for your test, and any flavour files you want. Stories may optionally be 
46 suffixed with a numeric timestamp (format YYYYMMDDHHMI) like the 
47 '1.txt.200607192254' entry above, which is used to set the modify time
48 of the story explicitly (since CVS does not store mtimes). Providing 
49 flavour files is recommended so that your tests don't break if the 
50 default flavours change. 
51  
52 At the top level of the test directory are a set of one or more
53 expected output files, and the spec.yaml files which controls the set
54 of tests that are run. For templates, the spec.yaml looks like this:
55
56   tests:
57     - 
58       - ""
59       - expected/index.html
60
61 This lists the set of tests to be run (in this case just a single test).
62 Each test requires a list of two arguments - the arguments to path to
63 blosxom.cgi (in this case none, an empty string), and a file containing
64 the expected output. So this test will execute blosxom.cgi with no 
65 arguments, and compare the output produced against that contained in
66 the 'expected.html' file.
67
68 A longer spec.yaml example is:
69
70   tests:
71     - 
72       - ""
73       - expected/index.html
74     -
75       - path=/foo
76       - expected/foo.html
77     -
78       - path=/foo/bar.html
79       - expected/bar.html
80
81 This defines three tests, one with no arguments, one with a path of 
82 /foo, and a third with a path of /foo/bar.html.
83