1 | karma-fixture [![Build Status](https://travis-ci.org/billtrik/karma-fixture.svg?branch=master)](https://travis-ci.org/billtrik/karma-fixture) [![NPM version](https://badge.fury.io/js/karma-fixture.svg)](http://badge.fury.io/js/karma-fixture)
|
2 | =============
|
3 |
|
4 | A plugin for the Karma test runner that loads `.html` and `.json` fixtures.
|
5 |
|
6 | It provides the same API as the teaspoon fixture package.
|
7 |
|
8 | Installation
|
9 | ------------
|
10 |
|
11 | Install the plugin from npm:
|
12 |
|
13 | ```sh
|
14 | $ npm install karma-fixture --save-dev
|
15 | ```
|
16 |
|
17 | Add `fixture` to the `frameworks` array in your Karma configuration:
|
18 |
|
19 | ```javascript
|
20 | module.exports = function(config){
|
21 | config.set({
|
22 | // ...
|
23 | frameworks: ['mocha', 'fixture'],
|
24 | // ...
|
25 | ```
|
26 |
|
27 | You also have to register any/all fixtures inside your Karma configuration file.
|
28 | If all your fixtures exist under a `fixtures/base/path/` folder, then you should include
|
29 | all files of interest under this base path.
|
30 |
|
31 |
|
32 | ```javascript
|
33 | module.exports = function(config){
|
34 | config.set({
|
35 | // ...
|
36 | files: [
|
37 | {
|
38 | pattern: 'fixtures/base/path/**/*',
|
39 | },
|
40 | // ...
|
41 | ],
|
42 | // ...
|
43 | ],
|
44 | ```
|
45 |
|
46 | Finally you have to add the `html2js` and `karma-json-fixtures-preprocessor` karma preprocessors:
|
47 |
|
48 | ```sh
|
49 | $ npm install karma-html2js-preprocessor --save-dev
|
50 | $ npm install karma-json-fixtures-preprocessor --save-dev
|
51 | ```
|
52 |
|
53 | , configure Karma to load all html and JSON fixture files via those preprocessors:
|
54 |
|
55 | ```javascript
|
56 | module.exports = function(config){
|
57 | config.set({
|
58 | // ...
|
59 | preprocessors: {
|
60 | '**/*.html' : ['html2js'],
|
61 | '**/*.json' : ['json_fixtures']
|
62 | },
|
63 | // ...
|
64 | ```
|
65 |
|
66 | and then setup the `karma-json-fixtures-preprocessor` plugin:
|
67 |
|
68 | ```javascript
|
69 | module.exports = function(config){
|
70 | config.set({
|
71 | // ...
|
72 | jsonFixturesPreprocessor: {
|
73 | variableName: '__json__'
|
74 | },
|
75 | // ...
|
76 | ```
|
77 |
|
78 | *(optional)* If the plugins won't get loaded by karma, you might have to declare them inside the `plugins` array in your Karma configuration
|
79 | *(and maybe load `karma-html2js-preprocessor` as well)*:
|
80 |
|
81 | ```javascript
|
82 | module.exports = function(config){
|
83 | config.set({
|
84 | // ...
|
85 | plugins: [
|
86 | 'karma-fixture',
|
87 | 'karma-html2js-preprocessor',
|
88 | 'karma-json-fixtures-preprocessor',
|
89 | // ...
|
90 | ],
|
91 | // ...
|
92 | ```
|
93 |
|
94 | Implementation details
|
95 | -----
|
96 |
|
97 | All html fixture files are pre-loaded as strings and placed inside the Karma-created `window.__html__` object and all json fixtures are loaded inside
|
98 | `window.__json__`.
|
99 |
|
100 | The fixture plugin is exposed in the `window.fixture` object on every test run.
|
101 | It loads fixture files from these objects and appends the created html inside the `window.fixture.el` element that gets created on start-up. It appends loaded JSONs inside the `fixture.json` array.
|
102 |
|
103 |
|
104 | Usage
|
105 | ------
|
106 |
|
107 | Lets say you have the following fixture files:
|
108 |
|
109 | - `fixtures/base/path/test1.html`
|
110 |
|
111 | ```html
|
112 | <p>p</p>
|
113 | <a href='#'>
|
114 | <span>link</span>
|
115 | </a>
|
116 | ```
|
117 |
|
118 | - `fixtures/base/path/json/test1.json`
|
119 | ```javascript
|
120 | "{"test":true}"
|
121 | ```
|
122 |
|
123 | You can use `fixture` inside your tests to handle the fixtures:
|
124 |
|
125 |
|
126 | ```javascript
|
127 | describe('some test that needs a fixture', function(){
|
128 | // If base path is different from the default `spec/fixtures`
|
129 | before(function(){
|
130 | fixture.setBase('fixtures/base/path')
|
131 | });
|
132 |
|
133 | beforeEach(function(){
|
134 | this.result = fixture.load('test1.html', 'test1.json');
|
135 | });
|
136 |
|
137 | afterEach(function(){
|
138 | fixture.cleanup()
|
139 | });
|
140 |
|
141 | it('plays with the html fixture', function(){
|
142 | expect(fixture.el.firstChild).to.equal(this.result[0][0]);
|
143 | });
|
144 |
|
145 | // ...
|
146 | });
|
147 | ```
|
148 |
|
149 | API
|
150 | -------
|
151 |
|
152 | * `fixture.el`
|
153 |
|
154 | Reference to the container element. Every html fixture loaded gets appended inside this container.
|
155 |
|
156 | * `fixture.json`
|
157 |
|
158 | An array of all json objects imported from fixture templates.
|
159 |
|
160 |
|
161 | * `fixture.load(files..., append = false)`
|
162 |
|
163 | It takes multiple filenames as arguments. All filenames are loaded from within the base path.
|
164 |
|
165 | It loads and appends them inside the fixtures container element.
|
166 | It returns an array with references to the newly created first level html elements.
|
167 | When more than one are loaded, it returns an array of the above described format, for each loaded fixture.
|
168 |
|
169 | It takes an optional boolean argument which defaults to `false`.
|
170 | If `false`, it empties the `window.fixture.el` container element and clears the `window.fixture.json` array.
|
171 | If `true`, it just appends the requested fixture to the container.
|
172 |
|
173 | If your fixtures exist in a base path other than the default `spec/fixtures`,
|
174 | you should call `fixture.setBase('fixtures/base/path')` in your specs, or load them
|
175 | with their full, base included, filenames prefixed with a '/'.
|
176 |
|
177 | For example: `fixture.load('/my/other/base/path/fixture1.html')`
|
178 |
|
179 | Scenarios:
|
180 |
|
181 | **html fixture**
|
182 |
|
183 | It returns an array of all the first-level nodes created by the fixture file:
|
184 |
|
185 | ```javascript
|
186 | html_fixture = fixture.load('test1.html');
|
187 | // then
|
188 | expect(html_fixture[0].innerHTML).to.equal('<p>p</p>')
|
189 | // and
|
190 | expect(html_fixture[1].innerHTML).to.equal('<a href="#"><span>link</span></a>')
|
191 | ```
|
192 |
|
193 | **JSON fixture**
|
194 |
|
195 | It returns a valid object by JSON.parsing the passed json fixture file.
|
196 | Also all JSON files loaded get appended to the `window.fixture.json` array:
|
197 |
|
198 | ```javascript
|
199 | json_fixture = fixture.load('json/test1.json')
|
200 | // then
|
201 | expect(json_fixture).to.eql({"test":true})
|
202 | // and
|
203 | expect(fixture.json[0]).to.eql({"test":true})
|
204 | ```
|
205 |
|
206 | **Multiple files**
|
207 |
|
208 | The result will be an array containing results of each loaded template:
|
209 |
|
210 | ```javascript
|
211 | loaded_fixtures = fixture.load('test1.html', 'json/test1.json')
|
212 | // then
|
213 | expect(loaded_fixtures[0][0].innerHTML).to.equal('<p>p</p>')
|
214 | // and
|
215 | expect(loaded_fixtures[0][1].innerHTML).to.equal('<a href="#"><span>link</span></a>')
|
216 | // and
|
217 | expect(loaded_fixtures[1]).to.eql({"test":true})
|
218 | // and
|
219 | expect(fixture.json[0]).to.eql({"test":true})
|
220 | ```
|
221 |
|
222 |
|
223 | * `fixture.set(html_strings, append=false)`
|
224 |
|
225 | It takes multiple html_strings as arguments and load them.
|
226 | It returns the loaded result, or an array of more than one loaded results
|
227 |
|
228 | It takes a boolean argument with default value `false`.
|
229 | If `false`, it empties the `window.fixture.el` container element and clears the `window.fixture.json` array.
|
230 |
|
231 |
|
232 | ```javascript
|
233 | result = fixture.set('<h1>test</h1>')
|
234 | // then
|
235 | expect(result[0].innerHTML).to.equal('<h1>test</h1>')
|
236 | ```
|
237 |
|
238 | * `fixture.cleanup()`
|
239 |
|
240 | It empties the `window.fixture.el` container element and clears the `window.fixture.json` array.
|
241 |
|
242 | * `fixture.setBase(fixtureBasePath)`
|
243 |
|
244 | It set the base path under which all forthcoming fixtures will be loaded.
|
245 | This can be bypassed by loading a fixture with its full, base included, filename prefixed with a '/'.
|
246 |
|
247 |
|
248 | License
|
249 | -------
|
250 |
|
251 | The MIT License (MIT)
|
252 |
|
\ | No newline at end of file |