Helpers to test Gulp processes
- Basic usage
- Options
- Using callbacks
- CAVEAT with callbacks
- Helper callbacks
nextTask
helper functioncompareTranspiled
helper functiondeleteFile
,isDeleted
andisFound
helper functionshas-sourcemap
helper functionisNewer
andisUntouched
helper functionsisSameContent
andisChangedContent
helper functionsnever
helper functionparallel
helper functionsnapshot
helper functiontouchFile
helper function
- License
Let's consider the gulpfile gulpfile.js
:
import gulp from 'gulp';
import babel from 'gulp-babel';
const glob = 'src/**/*.js';
const dest = 'build';
gulp.task('exec:transpile:all', () => {
return gulp.src(glob, {base: process.cwd()})
.pipe(babel())
.pipe(gulp.dest(dest));
});
gulp.task('default', gulp.series('exec:transpile:all'));
You want to test the correct succession of the tasks default
and exec:transpile:all
manifested when gulp
is run. Assuming a Mocha
-like test runner, you can do it by using the helper function testGulpProcess
.
import testGulpProcess from 'test-gulp-process';
describe('Testing gulpfile', function () {
it(`Testing a transpile task`, testGulpProcess({
sources: ['src/**/*.js', 'test/**/*.js'], // Source files copied into a tmp directory
gulpfile: 'test/gulpfiles/gulpfile.js', // Renamed automatically as gulpfile.babel.js into the tmp directory
messages: [
`Starting 'default'...`,
`Starting 'exec:transpile:all'...`,
`Finished 'exec:transpile:all' after`,
`Finished 'default' after`,
],
})); // the output of the gulp process is checked against the above messages
});
sources
: A glob pointing to the files to be used as sources for the test.gulpfile
: The gulpfile to be used for the test.task
(optional): The task with which to callgulp
. SeenextTask
helper function.messages
: An array of all the messages to be expected, in order, and of functions to be executed, in order. (see Using callbacks).
When a message is intercepted, a custom callback can be run:
import testGulpProcess from 'test-gulp-process';
describe('Testing gulpfile', function () {
it(`Testing a transpile task`, testGulpProcess({
sources: ['src/**/*.js', 'test/**/*.js'],
gulpfile: 'test/gulpfiles/gulpfile.js',
messages: [
`Starting 'default'...`,
`Starting 'exec:transpile:all'...`,
[`Finished 'exec:transpile:all' after`, () => {
throw new Error('Must still implement a test on correct transpilation')
}],
`Finished 'default' after`,
],
}));
});
Callbacks are not called at the actual operation time but when its logging message has been caught by the test runner. Therefore only use the callbacks when the tested process is idle (has finished its last batch of operations).
This means either when the spawned gulp processed has returned or when it is watching for a change that you can trigger explicitly with callbacks such as touchFile
or nextTask
. See the snapshot test as an example.
import testGulpProcess, {never, nextTask} from 'test-gulp-process';
describe('Testing Gulpfile task', function () {
it(`Series of tasks`, testGulpProcess({
sources: ['src/**/*.js', 'test/**/*.js'],
gulpfile: 'test/gulpfiles/exec-task.js',
task: ['hello', 'default', 'ciao'],
messages: [
never(`Starting 'default'...`),
never(`Starting 'ciao'...`),
`Starting 'hello'...`,
'hello',
[`Finished 'hello' after`, nextTask()],
never(`Starting 'hello'...`),
never(`Starting 'ciao'...`),
`Starting 'default'...`,
'coucou',
[`Finished 'default' after`, nextTask()],
never(`Starting 'hello'...`),
never(`Starting 'default'...`),
`Starting 'ciao'...`,
'ciao',
`Finished 'ciao' after`,
],
}));
});
import testGulpProcess, {compareTranspiled} from 'test-gulp-process';
describe('Testing gulpfile', function () {
it(`Testing a transpile task`, testGulpProcess({
sources: ['src/**/*.js', 'test/**/*.js'],
gulpfile: 'test/gulpfiles/gulpfile.js',
messages: [
`Starting 'default'...`,
`Starting 'exec:transpile:all'...`,
[`Finished 'exec:transpile:all' after`, compareTranspiled(
'src/**/*.js', 'build')], // Checks that the build dir contains the transpiled files from 'src/**/*.js'
`Finished 'default' after`,
],
}));
});
Using the gulpfile from touchFile
helper function, we can use deleteFile
to delete a file after a succession of events.
With isDeleted
and isFound
, we can check whether the file still exists or not.
import testGulpProcess, {touchFile} from 'test-gulp-process';
describe('Testing Gulpfile', function () {
it(`Testing a tdd transpile task`, testGulpProcess({
sources: ['src/**/*.js', 'test/**/*.js'],
gulpfile: 'test/gulpfiles/gulpfile.js',
messages: [
`Starting 'default'...`,
`Starting 'tdd:transpile:all'...`,
`Starting 'exec:transpile:all'...`,
[`Finished 'exec:transpile:all' after`, isFound('src/some-file.js')],
`Starting 'watch:transpile:all'...`,
`Finished 'watch:transpile:all' after`,
`Finished 'tdd:transpile:all' after`,
[`Finished 'default' after`, deleteFile('src/some-file.js')],
`Starting 'exec:transpile:all'...`,
[`Finished 'exec:transpile:all' after`, isDeleted('src/some-file.js')],
],
}));
});
has-sourcemap(glob, dest)
whether provided glob has its sourcemap converted files in the dest
directory.
In the following example, src/**/*.js
were transpiled, appended with associated source maps and written to build
. We check that the original glob can be restored identically from the files found in build
.
import testGulpProcess, {hasSourcemap, isFound} from 'test-gulp-process';
describe('Testing Gulpfile', function () {
it(`Testing a transpile task with sourcemaps`, testGulpProcess({
sources: ['src/**/*.js', 'test/**/*.js', 'gulp/**/*.js'],
gulpfile: 'test/gulpfiles/exec-sourcemaps.js',
messages: [
`Starting 'default'...`,
`Starting 'exec'...`,
[`Finished 'exec' after`,
isFound('src/test-gulp-process.js'),
isFound('build/src/test-gulp-process.js'),
hasSourcemap('src/**/*.js', 'build')],
`Finished 'default' after`,
],
}));
});
isNewer(glob)
will throw if at least one of glob files have not been touched since last snapshot
.
isUntouched(glob)
will throw if at least one of glob files have been touched since last snapshot
.
See snapshot
helper function example.
isSameContent(glob)
will throw if the content of at least one of glob files have been changed since last snapshot
.
isChangedContent(glob)
will throw if the content of at least one of glob files have not been changed since last snapshot
.
See snapshot
helper function example.
never
forbids the occurrence of a specific message among all the captured messages.
In the following example, as we launch the process for task hello
, the message concerning the default
task should never appear.
import testGulpProcess, {never} from 'test-gulp-process';
describe('Testing Gulpfile task', function () {
it(`Task is not default`, testGulpProcess({
sources: ['src/**/*.js', 'test/**/*.js', 'gulp/**/*.js'],
gulpfile: 'test/gulpfiles/exec-task.js',
task: 'hello',
messages: [
never(`Starting 'default'...`),
never(`Finished 'default' after`),
`Starting 'hello'...`,
'hello',
`Finished 'hello' after`,
],
}));
});
parallel
helps with intercepting concurrent logging threads, typically when running gulp
tasks in parallel.
import testGulpProcess, {parallel} from 'test-gulp-process';
describe('Testing Gulpfile', function () {
it(`Testing parallel queues`, testGulpProcess({
sources: ['src/**/*.js'],
gulpfile: 'test/gulpfiles/exec-queue.js',
messages: [
`Starting 'default'...`,
parallel(
['hello2', 'hello4', 'hello7'],
['hello1', 'hello3'],
['hello5'],
['hello6', 'hello8']
),
`Finished 'default' after`,
],
}));
it(`Testing parallel queues - fail on bad order`, testGulpProcess({
sources: ['src/**/*.js'],
gulpfile: 'test/gulpfiles/exec-queue.js',
messages: [
`Starting 'default'...`,
parallel(
['hello2', 'hello7', 'hello4'],
['hello1', 'hello3'],
['hello5'],
['hello6', 'hello8']
),
`Finished 'default' after`,
],
onCheckResultsError (err) {
expect(err.message).to.match(
/Waiting too long for child process to finish/);
expect(err.message).to.match(/'hello4' was never intercepted/);
},
}));
});
snapshot
takes a glob as argument and registers the content and the timestamps of the corresponding files. This snapshot is used by helpers isNewer
, isOlder
, isSameContent
and isDifferentContent
to assess the passed-through files.
import testGulpProcess, {snapshot, touchFile, isSameContent, isNewer}
from 'test-gulp-process';
describe('Testing snapshots', function () {
it(`Taking a snapshot and recovering`, testGulpProcess({
sources: ['src/**/*.js', 'test/**/*.js', 'gulp/**/*.js'],
gulpfile: 'test/gulpfiles/tdd-transpile-all.js',
messages: [
`Starting 'default'...`,
`Starting 'tdd:transpile:all'...`,
`Starting 'exec:transpile:all'...`,
`Finished 'exec:transpile:all' after`,
`Starting 'watch:transpile:all'...`,
`Finished 'watch:transpile:all' after`,
`Finished 'tdd:transpile:all' after`,
[`Finished 'default' after`,
snapshot('src/**/*.js'),
touchFile('src/test-gulp-process.js')],
`Starting 'exec:transpile:all'...`,
[`Finished 'exec:transpile:all' after`,
isNewer('src/test-gulp-process.js'),
isSameContent('src/test-gulp-process.js'),
],
],
}));
});
Considering the gulpfile:
import gulp from 'gulp';
import babel from 'gulp-babel';
const glob = 'src/**/*.js';
const dest = 'build';
gulp.task('exec:transpile:all', () => {
return gulp.src(glob, {base: process.cwd()})
.pipe(babel())
.pipe(gulp.dest(dest));
});
gulp.task('watch:transpile:all', done => {
gulp.watch(glob, gulp.series('exec:transpile:all'));
done();
});
gulp.task('tdd:transpile:all', gulp.series('exec:transpile:all',
'watch:transpile:all'));
gulp.task('default', gulp.series('tdd:transpile:all'));
We can test if files are correctly watched with helper function touchFile
:
import testGulpProcess, {touchFile} from 'test-gulp-process';
describe('Testing Gulpfile', function () {
it(`Testing a tdd transpile task`, testGulpProcess({
sources: ['src/**/*.js', 'test/**/*.js'],
gulpfile: 'test/gulpfiles/gulpfile.js',
messages: [
`Starting 'default'...`,
`Starting 'tdd:transpile:all'...`,
`Starting 'exec:transpile:all'...`,
`Finished 'exec:transpile:all' after`,
`Starting 'watch:transpile:all'...`,
`Finished 'watch:transpile:all' after`,
`Finished 'tdd:transpile:all' after`,
[`Finished 'default' after`, touchFile('src/some-file.js')],
`Starting 'exec:transpile:all'...`,
`Finished 'exec:transpile:all' after`,
],
}));
});
test-gulp-process is MIT licensed.
© 2017-2019 Jason Lenoble