Skip to content

Commit 3472afa

Browse files
BartvdsBartvds
committed
expanded README.md usage example
1 parent 68365b9 commit 3472afa

File tree

1 file changed

+134
-54
lines changed

1 file changed

+134
-54
lines changed

‎README.md

+134-54
Original file line numberDiff line numberDiff line change
@@ -21,73 +21,153 @@ Macros are powerful to define chains of targets for different plugins that toget
2121

2222
Check the [Gruntfile](https://github.com/Bartvds/gruntfile-gtx/blob/master/Gruntfile.js) for practical [dogfooding](https://en.wikipedia.org/wiki/Dogfooding) and [browse the tests](https://github.com/Bartvds/gruntfile-gtx/tree/master/test/spec) for some more options.
2323

24-
### Practical example
24+
### Example
2525

26-
The following snippets are lifted from the [gruntfile of TSD](https://github.com/DefinitelyTyped/tsd/blob/develop-0.5.x/Gruntfile.js) and show a macro to compile and run separated 'test modules'.
26+
The following code block shows many of the enhancement features. The macro example is lifted from the [gruntfile of TSD](https://github.com/DefinitelyTyped/tsd/blob/develop-0.5.x/Gruntfile.js) and shows a macro to compile and run separated 'test modules'.
2727

28-
The use-case makes test easier to run by splitting the test-suite over multiple semi-isolated folders for rapid (partial) TDD. Additionally separate 'modules' can also be run concurrently to cut down test duration for IO heavy topics.
28+
This specific macro aims to make the different project modules easier to run by splitting the test-suite over multiple separate folders. Additionally separate 'modules' can also be run concurrently to cut-down on overall test-duration for IO heavy topics.
2929

30-
Note the macro uses a few plugins to setup and run: it would be a hassle to maintain these modules in a regular gruntfile but easy when using a macro to build the chains.
30+
Note how the macro uses a few plugins to setup and run: it would be a hassle to maintain these modules in a regular gruntfile but it is easy when using a macro to build the chains.
3131

3232

3333
````js
34-
// define the macro
35-
// note the macro object is a context with helpers to assemble a new instance named 'id'
36-
gtx.define('module_tester', function (macro, id) {
37-
// let's use the instance id to build the path
38-
var testPath = 'test/modules/' + id + '/';
39-
40-
// create grunt-contrib-clean to remove old test output
41-
macro.newTask('clean', [testPath + 'tmp/**/*']);
42-
43-
// create grunt-ts task to compile the TypeScript test cases
44-
macro.newTask('ts', {
45-
options: {},
46-
src: [testPath + 'src/**/*.ts'],
47-
out: testPath + 'tmp/' + id + '.test.js'
34+
// export like any Gruntfile
35+
module.exports = function (grunt) {
36+
37+
// get the gtx instance
38+
var gtx = require('gruntfile-gtx').wrap(grunt);
39+
40+
// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
41+
42+
// load some plugins
43+
44+
gtx.loadNpm(
45+
'myPlugin',
46+
'myOtherPlugin'
47+
);
48+
gtx.loadTasks('./tasks');
49+
50+
// use bundled 'load-grunt-tasks'
51+
gtx.autoLoad();
52+
53+
// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
54+
55+
// basic configuration
56+
57+
// build the grunt config like the regular structure
58+
gtx.addConfig({
59+
pkg: grunt.file.readJSON('package.json'),
60+
myPlugin: {
61+
options: {
62+
//..
63+
},
64+
main: {
65+
src: ['./files/main/*.js']
66+
//..
67+
}
68+
},
69+
myOtherPlugin: {
70+
main: {
71+
src: ['./files/dev/*.js']
72+
//..
73+
}
74+
}
75+
});
76+
// ... but split over multiple statements
77+
gtx.addConfig({
78+
myPlugin: {
79+
dev: {
80+
src: ['./files/dev/*.js']
81+
//..
82+
}
83+
}
84+
});
85+
// directly set config object
86+
gtx.addConfigFor('myPlugin', 'beta', {
87+
src: ['./files/beta/*.js']
4888
});
49-
// run grunt-tslint
50-
macro.newTask('tslint', {
51-
src: [testPath + 'src/**/*.ts']
89+
// generate a unique name (note: this is the basis for the macro feature)
90+
var name = gtx.addConfigFor('myPlugin', {
91+
src: ['./files/gamma/*.js']
5292
});
53-
// optionally spawn a grunt-contrib-connect
54-
if (macro.getParam('http', 0) > 0) {
55-
macro.newTask('connect', {
93+
// do creative stuff by generating tasks (go wild here)
94+
gtx.alias('bulk_run', ['one', 'two', 'three'].map(function (name) {
95+
return gtx.addConfigFor('myPlugin', {
96+
src: ['./files/' + name + '/*.js']
97+
});
98+
}));
99+
100+
// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
101+
102+
// define a macro (lifted from practical use-case)
103+
104+
// note the macro object is a context with helpers to assemble a new instance named 'id'
105+
gtx.define('module_tester', function (macro, id) {
106+
// let's use the instance id to build a shared path
107+
var testPath = 'test/modules/' + id + '/';
108+
109+
// use grunt-contrib-clean to remove old test output
110+
macro.newTask('clean', [testPath + 'tmp/**/*']);
111+
112+
// use grunt-ts to compile the TypeScript test cases
113+
macro.newTask('ts', {
114+
options: {},
115+
src: [testPath + 'src/**/*.ts'],
116+
out: testPath + 'tmp/' + id + '.test.js'
117+
});
118+
// use grunt-tslint
119+
macro.newTask('tslint', {
120+
src: [testPath + 'src/**/*.ts']
121+
});
122+
// optionally spawn a grunt-contrib-connect
123+
if (macro.getParam('http', 0) > 0) {
124+
macro.newTask('connect', {
125+
options: {
126+
port: macro.getParam('http'),
127+
base: testPath + 'www/'
128+
}
129+
});
130+
//tag for easy retrieval
131+
macro.tag('http');
132+
}
133+
// run a regular task
134+
macro.runTask('myPlugin:dev');
135+
136+
// run grunt-mocha-test on the compiled test cases
137+
macro.newTask('mochaTest', {
56138
options: {
57-
port: macro.getParam('http'),
58-
base: testPath + 'www/'
59-
}
139+
timeout: macro.getParam('timeout', 2000)
140+
},
141+
src: [testPath + 'tmp/**/*.test.js']
60142
});
61-
//tag for easy retrieval
62-
macro.tag('http');
63-
}
64-
// run a regular task
65-
macro.runTask('mocha_unfunk:dev');
66-
// run grunt-mocha-test on the compiled test cases
67-
macro.newTask('mochaTest', {
68-
options: {
69-
timeout: macro.getParam('timeout', 2000)
70-
},
71-
src: [testPath + 'tmp/**/*.test.js']
143+
}, {
144+
// optionally run parallel using grunt-concurrent (for now only from gtx-type)
145+
concurrent: 4
72146
});
73-
}, {
74-
// optionally run using grunt-concurrent (for now only from gtx-type)
75-
concurrent: 4
76-
});
77-
78-
// now make some instances:
79-
gtx.create('git', 'module_tester', null, 'lib');
80-
gtx.create('tsd', 'module_tester', {timeout: 10000}, 'lib,core');
81-
gtx.create('http', 'module_tester', {
82-
timeout: 20000,
83-
http: 8080
84-
}, 'lib');
85-
86-
// make alias to run all instances as your $ grunt test
87-
gtx.alias('test', ['gtx-type:module_tester']);
147+
148+
// use the macro to make many instances
149+
gtx.create('git', 'module_tester', null, 'lib');
150+
gtx.create('tsd', 'module_tester', {timeout: 10000}, 'lib,core');
151+
gtx.create('http', 'module_tester', {
152+
timeout: 20000,
153+
http: 8080
154+
}, 'lib');
155+
gtx.create('basic,remote,local', 'module_tester');
156+
157+
// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
158+
159+
// let's make an alias to run all instances as your $ grunt test
160+
gtx.alias('test', ['gtx-type:module_tester']);
161+
162+
// alias is short-cut for grunt.registerTask();
163+
gtx.alias('default', ['test']);
164+
165+
// compile and send to the grunt.initConfig()
166+
gtx.finalise();
167+
};
88168
````
89169

90-
To run these:
170+
To run these macro instances:
91171
````
92172
$ grunt -h
93173
$ grunt gtx:git

0 commit comments

Comments
 (0)