Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 141 lines (99 sloc) 4.716 kB
6aaa8b7 @robwhitby tinkering with html output, added to readme
authored
1 # xray
2
45e1569 @robwhitby update readme
authored
3 **xray** is a framework for writing XQuery unit tests on MarkLogic Server. Test cases are written as standard XQuery functions like this:
6aaa8b7 @robwhitby tinkering with html output, added to readme
authored
4
5 ```xquery
399ff64 @robwhitby remove unnecessary test function prefix
authored
6 declare function string-equality-example()
6aaa8b7 @robwhitby tinkering with html output, added to readme
authored
7 {
8 let $foo := "foo"
9 return assert:equal($foo, "foo")
10 };
11 ```
12
13 ## Getting Started
909365c @robwhitby bit of refactoring
authored
14 * Clone/copy/symlink xray into the root directory of your project e.g.<br/>
efe12dc @robwhitby Update README.md
authored
15 `git clone git://github.com/robwhitby/xray.git`
16 or
ee9c1c8 @robwhitby add git submodule command to readme
authored
17 `git submodule add git://github.com/robwhitby/xray.git`
6aaa8b7 @robwhitby tinkering with html output, added to readme
authored
18 * Create an HTTP app server pointing to the root directory of your project.
19 * Check all is well at `http://server:port/xray/`
20 * Write some tests..
21
22
23 ## Writing Tests
9867df7 @robwhitby add sample code to html output when no tests found
authored
24 Tests are grouped into library modules in the xray test namespace. Import the xray assertions module along with the modules to be tested.
6aaa8b7 @robwhitby tinkering with html output, added to readme
authored
25
26 ```xquery
998f4e7 @robwhitby Remove reliance on namespace prefix for test functions
authored
27 xquery version "1.0-ml";
28 module namespace test = "http://github.com/robwhitby/xray/test";
29 import module namespace assert = "http://github.com/robwhitby/xray/assertions" at "/xray/src/assertions.xqy";
6aaa8b7 @robwhitby tinkering with html output, added to readme
authored
30
26ec1c7 @robwhitby add assert function signatures and module import to readme
authored
31 import module namespace some-module = "http://some-module-to-test" at "/some-module-to-test.xqy";
32
399ff64 @robwhitby remove unnecessary test function prefix
authored
33 declare function string-equality-example()
6aaa8b7 @robwhitby tinkering with html output, added to readme
authored
34 {
bc01982 @robwhitby implemented ignoring tests by test naming convention
authored
35 let $foo := some-module:foo()
6aaa8b7 @robwhitby tinkering with html output, added to readme
authored
36 return assert:equal($foo, "foo")
37 };
38
bc01982 @robwhitby implemented ignoring tests by test naming convention
authored
39 declare function multiple-assert-example()
399ff64 @robwhitby remove unnecessary test function prefix
authored
40 {
26ec1c7 @robwhitby add assert function signatures and module import to readme
authored
41 let $foo := some-module:foo()
399ff64 @robwhitby remove unnecessary test function prefix
authored
42 let $bar := "bar"
43 return (
44 assert:not-empty($foo),
45 assert:equal($foo, "foo"),
46 assert:not-equal($foo, $bar)
47 )
48 };
49
6aaa8b7 @robwhitby tinkering with html output, added to readme
authored
50 (: more tests :)
51 ```
52
53 ## Invoking Tests
bc01982 @robwhitby implemented ignoring tests by test naming convention
authored
54 **xray** will find and execute all the test cases defined in a directory (including sub-directories), and can be told to execute a subset by specifying regex patterns to match tests by module name or test name.
6aaa8b7 @robwhitby tinkering with html output, added to readme
authored
55
998f4e7 @robwhitby Remove reliance on namespace prefix for test functions
authored
56 * browser - `http://server:port/xray/`
2c6ba36 @robwhitby more readme changes
authored
57 * command line - call `test-runner.sh` with your project parameters (see below, tested on OSX only).
998f4e7 @robwhitby Remove reliance on namespace prefix for test functions
authored
58 * invoke from xquery - import `src/xray.xqy` and call `xray:run-tests()`. See `index.xqy` for example.
6aaa8b7 @robwhitby tinkering with html output, added to readme
authored
59
c30d724 @robwhitby Update README.md
authored
60 By default, xray looks for a directory called `test` at the same level as the `xray` directory:
61 <pre>
62 project-root/
63 ├── src
64 ├── test
65 │   └── tests.xqy
66 └── xray
67 </pre>
6aaa8b7 @robwhitby tinkering with html output, added to readme
authored
68
c30d724 @robwhitby Update README.md
authored
69 To invoke tests stored elsewhere, set the directory parameter.
8551407 @robwhitby fix markdown formatting
authored
70
71
2c6ba36 @robwhitby more readme changes
authored
72 ## Test Runner Command Line Parameters
c30d724 @robwhitby Update README.md
authored
73 `-d` test directory path relative from the app server modules root. Optional, defaults to "test".
74
75 `-m` regex match on module name. Optional, default to match all.
76
77 `-t` regex match on test name. Optional, defaults to match all.
78
79 `-u` the url of the MarkLogic HTTP app server to connect to.
80
2c6ba36 @robwhitby more readme changes
authored
81 ## Test Runner Shortcut
c30d724 @robwhitby Update README.md
authored
82 Rather than modify test-runner.sh or always pass in custom parameters, it's handy to create a small wrapper script in the project root, something like this:
83
84 ```shell
85 ./xray/test-runner.sh -u http://localhost:8765/xray/ -d testdir $*
86 ```
8551407 @robwhitby fix markdown formatting
authored
87
2c6ba36 @robwhitby more readme changes
authored
88 This still allows using `-t` and `-m` to select which tests to run but removes the need to constantly set the url and test directory.
89
e068249 @robwhitby added shortcut to run xray tests and update readme
authored
90 See `run-xray-tests.sh` for an example.
91
6aaa8b7 @robwhitby tinkering with html output, added to readme
authored
92
93 ## Assertions
26ec1c7 @robwhitby add assert function signatures and module import to readme
authored
94 ```xquery
1213f68 @robwhitby readme tweaks
authored
95 assert:equal ($actual as item()*, $expected as item()*)
efe12dc @robwhitby Update README.md
authored
96
1213f68 @robwhitby readme tweaks
authored
97 assert:not-equal ($actual as item()*, $expected as item()*)
efe12dc @robwhitby Update README.md
authored
98
1213f68 @robwhitby readme tweaks
authored
99 assert:empty ($actual as item()*)
efe12dc @robwhitby Update README.md
authored
100
1213f68 @robwhitby readme tweaks
authored
101 assert:not-empty ($actual as item()*)
efe12dc @robwhitby Update README.md
authored
102
1213f68 @robwhitby readme tweaks
authored
103 assert:error ($actual as item()*, $expected-error-name as xs:string)
efe12dc @robwhitby Update README.md
authored
104
1213f68 @robwhitby readme tweaks
authored
105 assert:true ($actual as item()*)
efe12dc @robwhitby Update README.md
authored
106
1213f68 @robwhitby readme tweaks
authored
107 assert:false ($actual as item()*)
9867df7 @robwhitby add sample code to html output when no tests found
authored
108 ```
26ec1c7 @robwhitby add assert function signatures and module import to readme
authored
109 See `src/assertions.xqy` for the assertion definitions.
6aaa8b7 @robwhitby tinkering with html output, added to readme
authored
110
111 ## Setup and teardown functions
9867df7 @robwhitby add sample code to html output when no tests found
authored
112 `setup()` and `teardown()` are special function signatures. If defined, `setup()` is invoked before any tests, and in a different transaction so any database updates are visible to the tests. `teardown()` is executed after all tests in that module have finished.
6aaa8b7 @robwhitby tinkering with html output, added to readme
authored
113
81ebb81 @robwhitby fixing links
authored
114 See `test/tests.xqy` for an example.
6aaa8b7 @robwhitby tinkering with html output, added to readme
authored
115
45e1569 @robwhitby update readme
authored
116 ## Ignoring Tests
6c4bf90 @robwhitby typo
authored
117 Tests can be ignored by addding the prefix `IGNORE` to the test function name.
bc01982 @robwhitby implemented ignoring tests by test naming convention
authored
118
119 ```xquery
120 declare function IGNORE-this-test-will-be-ignored()
121 ```
6aaa8b7 @robwhitby tinkering with html output, added to readme
authored
122
f33fe7d @robwhitby update readme with required execute privileges
authored
123 ## MarkLogic Configuration
124 The app server user must belong to a role with the following execute privileges:
125 `xdmp:eval`, `xdmp:filesystem-directory`, `xdmp:filesystem-file`, `xdmp:invoke`, `xdmp:xslt-invoke`
126
206df98 @robwhitby added support for modules stored in db
authored
127 To work with modules stored in a modules database, the additional privileges are required:
128 `xdmp:eval-in`
129 And the user must have read rights to files in the modules db.
130
f33fe7d @robwhitby update readme with required execute privileges
authored
131 Test modules must be written in XQuery version "1.0-ml" to be parsed correctly.
132
909365c @robwhitby bit of refactoring
authored
133
6aaa8b7 @robwhitby tinkering with html output, added to readme
authored
134 ## Acknowledgements
f33fe7d @robwhitby update readme with required execute privileges
authored
135 Thanks to Gunther Rademacher's [REx Parser Generator](http://www.bottlecaps.de/rex/) and [John Snelson](http://github.com/jpcs) for the XQuery 1.0-ml parser.
9867df7 @robwhitby add sample code to html output when no tests found
authored
136
b6bef17 @robwhitby set ignored colour in shell, add screenshot
authored
137 &nbsp;
138 ## Screenshots
139 ![screenshot of html output](https://github.com/robwhitby/xray/raw/master/screenshot-html.png)
140 ![screenshot of terminal output](https://github.com/robwhitby/xray/raw/master/screenshot-terminal.png)
Something went wrong with that request. Please try again.