Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 137 lines (97 sloc) 4.523 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/`
57 * command line - test-runner.sh is a sample shell script, edit the default vars (tested on OSX only).
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
c30d724 @robwhitby Update README.md
authored
72 ## Command Line Parameters
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
81 ## Command-Line Shortcut
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
6aaa8b7 @robwhitby tinkering with html output, added to readme
authored
88
89 ## Assertions
26ec1c7 @robwhitby add assert function signatures and module import to readme
authored
90 ```xquery
91 assert:equal($actual as item()*, $expected as item()*)
efe12dc @robwhitby Update README.md
authored
92
26ec1c7 @robwhitby add assert function signatures and module import to readme
authored
93 assert:not-equal($actual as item()*, $expected as item()*)
efe12dc @robwhitby Update README.md
authored
94
26ec1c7 @robwhitby add assert function signatures and module import to readme
authored
95 assert:empty($actual as item()*)
efe12dc @robwhitby Update README.md
authored
96
26ec1c7 @robwhitby add assert function signatures and module import to readme
authored
97 assert:not-empty($actual as item()*)
efe12dc @robwhitby Update README.md
authored
98
26ec1c7 @robwhitby add assert function signatures and module import to readme
authored
99 assert:error($actual as item()*, $expected-error-name as xs:string)
efe12dc @robwhitby Update README.md
authored
100
9867df7 @robwhitby add sample code to html output when no tests found
authored
101 assert:true($actual as item()*)
efe12dc @robwhitby Update README.md
authored
102
9867df7 @robwhitby add sample code to html output when no tests found
authored
103 assert:false($actual as item()*)
104 ```
26ec1c7 @robwhitby add assert function signatures and module import to readme
authored
105 See `src/assertions.xqy` for the assertion definitions.
6aaa8b7 @robwhitby tinkering with html output, added to readme
authored
106
107 ## Setup and teardown functions
9867df7 @robwhitby add sample code to html output when no tests found
authored
108 `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
109
81ebb81 @robwhitby fixing links
authored
110 See `test/tests.xqy` for an example.
6aaa8b7 @robwhitby tinkering with html output, added to readme
authored
111
45e1569 @robwhitby update readme
authored
112 ## Ignoring Tests
6c4bf90 @robwhitby typo
authored
113 Tests can be ignored by addding the prefix `IGNORE` to the test function name.
bc01982 @robwhitby implemented ignoring tests by test naming convention
authored
114
115 ```xquery
116 declare function IGNORE-this-test-will-be-ignored()
117 ```
6aaa8b7 @robwhitby tinkering with html output, added to readme
authored
118
f33fe7d @robwhitby update readme with required execute privileges
authored
119 ## MarkLogic Configuration
120 The app server user must belong to a role with the following execute privileges:
121 `xdmp:eval`, `xdmp:filesystem-directory`, `xdmp:filesystem-file`, `xdmp:invoke`, `xdmp:xslt-invoke`
122
206df98 @robwhitby added support for modules stored in db
authored
123 To work with modules stored in a modules database, the additional privileges are required:
124 `xdmp:eval-in`
125 And the user must have read rights to files in the modules db.
126
f33fe7d @robwhitby update readme with required execute privileges
authored
127 Test modules must be written in XQuery version "1.0-ml" to be parsed correctly.
128
909365c @robwhitby bit of refactoring
authored
129
6aaa8b7 @robwhitby tinkering with html output, added to readme
authored
130 ## Acknowledgements
f33fe7d @robwhitby update readme with required execute privileges
authored
131 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
132
b6bef17 @robwhitby set ignored colour in shell, add screenshot
authored
133 &nbsp;
134 ## Screenshots
135 ![screenshot of html output](https://github.com/robwhitby/xray/raw/master/screenshot-html.png)
136 ![screenshot of terminal output](https://github.com/robwhitby/xray/raw/master/screenshot-terminal.png)
Something went wrong with that request. Please try again.