643 lines
19 KiB
JavaScript
643 lines
19 KiB
JavaScript
/**
|
|
* Tests trait providing 1-N message dispatch
|
|
*
|
|
* Copyright (C) 2014 Mike Gerwitz
|
|
*
|
|
* This file is part of jsTonic.
|
|
*
|
|
* jstonic is free software: you can redistribute it and/or modify
|
|
* it under the terms of the GNU General Public License as published by
|
|
* the Free Software Foundation, either version 3 of the License, or
|
|
* (at your option) any later version.
|
|
*
|
|
* This program is distributed in the hope that it will be useful,
|
|
* but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
* GNU General Public License for more details.
|
|
*
|
|
* You should have received a copy of the GNU General Public License
|
|
* along with this program. If not, see <http://www.gnu.org/licenses/>.
|
|
*/
|
|
|
|
var Sut = require( '../../' ).event.Evented,
|
|
Eventable = require( '../../' ).event.Eventable,
|
|
|
|
Class = require( 'easejs' ).Class,
|
|
expect = require( 'chai' ).expect,
|
|
common = require( '../lib' ),
|
|
|
|
|
|
EvStub = Class.use( Sut ).extend(
|
|
{
|
|
// defineEvents is protected
|
|
evDefineEvents( ids )
|
|
{
|
|
return this.defineEvents( ids );
|
|
},
|
|
|
|
// emit is protected
|
|
evEmit( ev )
|
|
{
|
|
return this.emit.apply( this, arguments );
|
|
}
|
|
} );
|
|
|
|
|
|
describe( 'event.Evented', () =>
|
|
{
|
|
var stub;
|
|
|
|
beforeEach( () =>
|
|
{
|
|
stub = EvStub();
|
|
} );
|
|
|
|
|
|
/**
|
|
* As a general-purpose library, we would not want to restrict
|
|
* developers to a specific event implementation (for example, maybe the
|
|
* user would prefer to use Node.js' event system, or transparently
|
|
* integrate with libraries/systems that use it). Together with ease.js'
|
|
* interop support, this makes such a case trivial.
|
|
*/
|
|
describe( 'interface', () =>
|
|
{
|
|
it( 'is Eventable', () =>
|
|
expect( Class.isA( Eventable, stub ) ).to.be.true
|
|
);
|
|
} );
|
|
|
|
|
|
describe( '#defineEvents', () =>
|
|
{
|
|
/**
|
|
* We aren't going to bother testing every possibly value; let's
|
|
* just see if the most common case (probably) is caught.
|
|
*/
|
|
it( 'rejects non-array argument', () =>
|
|
{
|
|
expect( () => stub.evDefineEvents( 'string' ) )
|
|
.to.throw( TypeError, "array" );
|
|
} );
|
|
|
|
|
|
it( 'accepts array argument', () =>
|
|
{
|
|
expect( () => stub.evDefineEvents( [] ) )
|
|
.to.not.throw( TypeError );
|
|
} );
|
|
|
|
|
|
it( 'returns self', () =>
|
|
{
|
|
expect( stub.evDefineEvents( [] ) ).to.equal( stub );
|
|
} );
|
|
|
|
|
|
/**
|
|
* This relies on functionality proved below
|
|
*/
|
|
it( 'defines each event in provided list', () =>
|
|
{
|
|
var events = [ 'a', 'b' ];
|
|
stub.evDefineEvents( events );
|
|
|
|
var i = events.length;
|
|
while ( i-- ) {
|
|
// will fail if event did not register
|
|
expect( () => stub.on( events[ i ], ()=>{} ) )
|
|
.to.not.throw( Error );
|
|
}
|
|
} );
|
|
|
|
|
|
/**
|
|
* While at first glance this may seem like an odd thing to want to
|
|
* do, this will come in useful when exposed via an API that defines
|
|
* events individually.
|
|
*/
|
|
it( 'merges definitions in multiple calls', () =>
|
|
{
|
|
var evs = [ 'a', 'b' ];
|
|
|
|
// define each separately
|
|
for ( var i = 0; i < evs.length; i++ ) {
|
|
stub.evDefineEvents( [ evs[ i ] ] );
|
|
|
|
// will fail if event did not register
|
|
expect( () => stub.on( evs[ i ], ()=>{} ) )
|
|
.to.not.throw( Error );
|
|
}
|
|
} );
|
|
|
|
|
|
/**
|
|
* We do not want someone to declare an event thinking that the id
|
|
* is free, which risks mixing handlers from what is supposed to be
|
|
* two separate events.
|
|
*/
|
|
describe( 'throws exception on duplicate events', () =>
|
|
{
|
|
it( 'in separate calls', () =>
|
|
{
|
|
var name = 'ev';
|
|
stub.evDefineEvents( [ name ] );
|
|
|
|
expect( () => stub.evDefineEvents( [ name ] ) )
|
|
.to.throw( Error, name );
|
|
} );
|
|
|
|
|
|
it( 'in a single call', () =>
|
|
{
|
|
var dup = 'foo';
|
|
|
|
expect( () => stub.evDefineEvents( [ dup, 'a', dup ] ) )
|
|
.to.throw( Error, dup );
|
|
} );
|
|
} );
|
|
} );
|
|
|
|
|
|
/**
|
|
* `addListener` is an alias for `on` (consistent with Node.js' API)
|
|
*/
|
|
[ 'on', 'addListener' ].forEach( on =>
|
|
{
|
|
describe( ( '#' + on ), () =>
|
|
{
|
|
it( 'does not allow hooking undeclared events', () =>
|
|
{
|
|
var badevent = 'bazbar';
|
|
|
|
expect( () => stub[ on ]( badevent, ()=>{} ) )
|
|
.to.throw( Error, badevent );
|
|
} );
|
|
|
|
|
|
it( 'allows hooking declared events', () =>
|
|
{
|
|
var name = 'testev';
|
|
stub.evDefineEvents( [ name ] )
|
|
[ on ]( name, ()=>{} );
|
|
} );
|
|
|
|
|
|
it( 'returns self', () =>
|
|
{
|
|
var name = 'testev';
|
|
|
|
var ret = stub.evDefineEvents( [ name ] )
|
|
[ on ]( name, ()=>{} );
|
|
|
|
expect( ret ).to.equal( stub );
|
|
} );
|
|
|
|
|
|
it( 'requires that listener is a function', () =>
|
|
{
|
|
var ev = 'foo';
|
|
stub.evDefineEvents( [ ev ] );
|
|
|
|
// OK
|
|
expect( () => stub[ on ]( ev, ()=>{} ) )
|
|
.to.not.throw( TypeError );
|
|
|
|
// bad
|
|
expect( () => stub[ on ]( ev, "kittens" ) )
|
|
.to.throw( TypeError );
|
|
} );
|
|
|
|
|
|
/**
|
|
* It is highly suspect if the exact same listener is registered
|
|
* for the same event---it is either a bug, or a questionable
|
|
* design decision; we assume that the former is far more likely
|
|
* to be true, and that the latter should be addressed and
|
|
* resolved.
|
|
*
|
|
* Note that this does not prevent a caller from wrapping a
|
|
* listener in a function that is instead registered as the
|
|
* listener---this is perfectly valid and has many use cases.
|
|
*/
|
|
it( 'does not permit same event listener multiple times', () =>
|
|
{
|
|
var ev = 'foo',
|
|
f = () => {};
|
|
|
|
expect( () =>
|
|
{
|
|
stub.evDefineEvents( [ ev ] )
|
|
[ on ]( ev, f )
|
|
[ on ]( ev, f );
|
|
} ).to.throw( Error );
|
|
} );
|
|
} );
|
|
} );
|
|
|
|
|
|
describe( '#emit', () =>
|
|
{
|
|
it( 'cannot emit undefined events', () =>
|
|
{
|
|
var ev = 'unknown';
|
|
|
|
expect( () => stub.evEmit( ev ) )
|
|
.to.throw( Error, ev );
|
|
} );
|
|
|
|
|
|
it( 'invokes all listeners attached with #on', () =>
|
|
{
|
|
var ev = 'foo',
|
|
called = 0;
|
|
|
|
stub.evDefineEvents( [ ev ] )
|
|
.on( ev, () => called++ );
|
|
|
|
expect( () => stub.evEmit( ev ) )
|
|
.to.not.throw( Error );
|
|
|
|
// make sure the listener was invoked only once
|
|
expect( called ).to.equal( 1 );
|
|
} );
|
|
|
|
|
|
/**
|
|
* It is courteous for event handler to *not* modify the values they
|
|
* are given. Otherwise, the emitter must take care to clone or
|
|
* encapsulate the values if this is a concern.
|
|
*/
|
|
it( 'passes all emit args by reference to listeners', ( done ) =>
|
|
{
|
|
var ev = 'foo',
|
|
a = {},
|
|
b = [];
|
|
|
|
stub.evDefineEvents( [ ev ] )
|
|
.on( ev, ( givena, givenb ) =>
|
|
{
|
|
expect( givena ).to.equal( a );
|
|
expect( givenb ).to.equal( b );
|
|
done();
|
|
} )
|
|
.evEmit( ev, a, b );
|
|
} );
|
|
|
|
|
|
/**
|
|
* The default event scheduler synchronously invokes all listeners
|
|
* in an undefined order (that is: the order may change in the
|
|
* future). This is not desirable for all cases, but that's not the
|
|
* point here.
|
|
*/
|
|
it( 'invokes multiple listeners synchronously', () =>
|
|
{
|
|
var ev = 'foo',
|
|
called = [],
|
|
n = 2;
|
|
|
|
stub.evDefineEvents( [ ev ] );
|
|
|
|
// add N listeners for EV
|
|
for ( let i = 0; i < n; i++ ) {
|
|
stub.on( ev, () => called[ i ] = true );
|
|
}
|
|
|
|
// trigger listeners
|
|
stub.evEmit( ev );
|
|
|
|
// by now, we care about two things: that all listeners were
|
|
// invoked and that they have been invoked by this point,
|
|
// meaning that they were done synchronously
|
|
while ( n-- ) {
|
|
expect( called[ n ] ).to.equal( true );
|
|
}
|
|
} );
|
|
|
|
|
|
/**
|
|
* When we emit an event, only the listeners for that specific event
|
|
* should be invoked.
|
|
*/
|
|
it( 'does not mix listeners from other events', () =>
|
|
{
|
|
var ev = 'foo',
|
|
wrongev = 'bar';
|
|
|
|
stub.evDefineEvents( [ ev, wrongev ] );
|
|
|
|
var called = false;
|
|
stub.on( ev, () => called = true );
|
|
stub.on( wrongev, () => { throw Error( "Thar be demons" ) } );
|
|
|
|
// wrongev listeners should *not* be called
|
|
stub.evEmit( ev );
|
|
expect( called ).to.equal( true );
|
|
} );
|
|
|
|
|
|
/**
|
|
* It is common to leave events unhooked.
|
|
*/
|
|
it( 'does not fail when emitting unhooked events', () =>
|
|
{
|
|
var ev = 'foo';
|
|
expect( () => stub.evDefineEvents( [ ev ] ).evEmit( ev ) )
|
|
.to.not.throw( Error );
|
|
} );
|
|
|
|
|
|
it( 'returns self', () =>
|
|
{
|
|
var ev = 'foo';
|
|
expect( stub.evDefineEvents( [ ev ] ).evEmit( ev ) )
|
|
.to.equal( stub );
|
|
} );
|
|
} );
|
|
|
|
|
|
/**
|
|
* This is important to support stackable traits for custom schedulers.
|
|
*/
|
|
describe( '#scheduleCallbacks', () =>
|
|
{
|
|
var ev = 'foo',
|
|
a = 'bar',
|
|
b = 'baz';
|
|
|
|
it( 'can be overridden by subtypes', ( done ) =>
|
|
{
|
|
common.checkOverride( EvStub, 'scheduleCallbacks',
|
|
( given_ev, _, given_args ) =>
|
|
{
|
|
expect( given_ev ).to.equal( ev );
|
|
expect( given_args ).to.deep.equal( [ a, b ] );
|
|
done();
|
|
}
|
|
)().evDefineEvents( [ ev ] ).evEmit( ev, a, b );
|
|
} );
|
|
|
|
|
|
/**
|
|
* The listeners are encapsulated within the trait, so they must be
|
|
* passed to us for processing.
|
|
*/
|
|
it( 'is provided with listeners to invoke', ( done ) =>
|
|
{
|
|
var a = function() {},
|
|
b = function() {};
|
|
|
|
common.checkOverride( EvStub, 'scheduleCallbacks',
|
|
( _, evc, __ ) =>
|
|
{
|
|
expect( evc ).to.include( a );
|
|
expect( evc ).to.include( b );
|
|
done();
|
|
}
|
|
)()
|
|
.evDefineEvents( [ ev ] )
|
|
.on( ev, a )
|
|
.on( ev, b )
|
|
.evEmit( ev );
|
|
} );
|
|
} );
|
|
|
|
|
|
/**
|
|
* Permits additional actions on hook and overriding event hooking
|
|
* storage behavior
|
|
*/
|
|
describe( '#hookEvent', function()
|
|
{
|
|
var ev = 'foo',
|
|
f = ()=>{};
|
|
|
|
it( 'can be overridden by subtypes', ( done ) =>
|
|
{
|
|
common.checkOverride( EvStub, 'hookEvent',
|
|
( given_ev, given_callback ) =>
|
|
{
|
|
expect( given_ev ).to.equal( ev );
|
|
expect( given_callback ).to.equal( f );
|
|
done();
|
|
}
|
|
)().evDefineEvents( [ ev ] ).on( ev, f );
|
|
} );
|
|
|
|
|
|
/**
|
|
* Should provide full control over how the listeners are handled.
|
|
*/
|
|
it( 'can prevent listeners from being added', () =>
|
|
{
|
|
var ev = 'foo';
|
|
|
|
// override does nothing
|
|
expect( () =>
|
|
{
|
|
EvStub.extend(
|
|
{
|
|
'override hookEvent': ( _, __ ) => {}
|
|
} )()
|
|
.evDefineEvents( [ ev ] )
|
|
.on( ev, () =>
|
|
{
|
|
throw Error( "Event called!" );
|
|
} ).evEmit( ev );
|
|
} ).to.not.throw( Error );
|
|
} );
|
|
} );
|
|
|
|
|
|
describe( '#removeListener', () =>
|
|
{
|
|
it( 'rejects unknown event ids', () =>
|
|
{
|
|
var ev = 'foo';
|
|
expect( () => stub.removeListener( ev , ()=>{} ) )
|
|
.to.throw( Error, ev );
|
|
} );
|
|
|
|
|
|
/**
|
|
* The purpose of removing a listener is to prevent it from being
|
|
* called when an event is emitted. We don't really care how this is
|
|
* done; just don't call it.
|
|
*/
|
|
it( 'prevents removed listener from being called', () =>
|
|
{
|
|
var ev = 'foo',
|
|
called = false,
|
|
listener = ( () => called = true );
|
|
|
|
stub.evDefineEvents( [ ev ] );
|
|
|
|
// we have already proved that adding a listener works;
|
|
// immediately remove it and ensure that it's not called
|
|
stub.on( ev, listener )
|
|
.removeListener( ev, listener );
|
|
|
|
stub.evEmit( ev );
|
|
expect( called ).to.equal( false );
|
|
} );
|
|
|
|
|
|
/**
|
|
* If the given listener to remove was never registered (or no
|
|
* longer is), then we will shall act as though it was successfully
|
|
* removed (since, according to our initial requirement, we
|
|
* succeeded in ensuring that the listener will not be called on
|
|
* subsequent emits).
|
|
*/
|
|
it( 'does not fail and returns self on missing listener', () =>
|
|
{
|
|
let ev = 'foo';
|
|
|
|
expect(
|
|
stub.evDefineEvents( [ ev ] )
|
|
.removeListener( ev, () => {} )
|
|
).to.equal( stub );
|
|
} );
|
|
|
|
|
|
it( 'returns self on success', () =>
|
|
{
|
|
let ev = 'foo',
|
|
f = () => {};
|
|
|
|
expect(
|
|
stub.evDefineEvents( [ ev ] )
|
|
.on( ev, f )
|
|
.removeListener( ev, f )
|
|
).to.equal( stub );
|
|
} );
|
|
|
|
|
|
/**
|
|
* These are tests that are not design per se, but are intended to
|
|
* comprehensively guard against future design changes, likely or
|
|
* not.
|
|
*/
|
|
describe( 'sanity check', () =>
|
|
{
|
|
/**
|
|
* Removing a single listener for an event should not touch
|
|
* others for that same event
|
|
*/
|
|
it( 'does not remove all listeners for event', () =>
|
|
{
|
|
var ev = 'foo',
|
|
f1c = false,
|
|
f2c = false,
|
|
f1 = () => f1c = true,
|
|
f2 = () => f2c = true;
|
|
|
|
stub.evDefineEvents( [ ev ] )
|
|
.on( ev, f1 )
|
|
.on( ev, f2 )
|
|
.removeListener( ev, f1 )
|
|
.evEmit( ev );
|
|
|
|
expect( f1c ).to.be.false;
|
|
expect( f2c ).to.be.true;
|
|
} );
|
|
|
|
|
|
/**
|
|
* The same listener may be added to multiple events---we should
|
|
* only ever remove it from the one that was requested. We have
|
|
* already proven in previous tests that event listeners are
|
|
* actually removed as expected, so we need only ensure that it
|
|
* is *not* removed from another event that it is attached to.
|
|
*/
|
|
it( 'does not remove same listener on other events', () =>
|
|
{
|
|
var evs = [ 'foo', 'bar' ],
|
|
called = false,
|
|
f = () => called = true;
|
|
|
|
stub.evDefineEvents( evs )
|
|
.on( evs[ 0 ], f )
|
|
.on( evs[ 1 ], f )
|
|
.removeListener( evs[ 0 ], f )
|
|
.evEmit( evs[ 1 ] );
|
|
|
|
expect( called ).to.be.true;
|
|
} );
|
|
|
|
|
|
/**
|
|
* Removing a listener may introduce, depending on
|
|
* implementation details that we do not care about here, gaps
|
|
* in the data structure holding the listeners. The idea here is
|
|
* to ensure that this gap, if immediately filled, will not
|
|
* cause problems.
|
|
*/
|
|
it( 'can add listener after removal', () =>
|
|
{
|
|
var ev = 'foo',
|
|
called = 0,
|
|
frm = () => {},
|
|
fok = () => called++,
|
|
fok2 = () => called += 2;
|
|
|
|
stub.evDefineEvents( [ ev ] )
|
|
.on( ev, frm )
|
|
.removeListener( ev, frm )
|
|
.on( ev, fok )
|
|
.on( ev, fok2 )
|
|
.evEmit( ev );
|
|
|
|
expect( called ).to.equal( 3 );
|
|
} );
|
|
|
|
|
|
/**
|
|
* Similar to the above test, but ensures that the system is not
|
|
* marking a listener for deletion in such a way that it won't
|
|
* be recognized later. This would be an odd implementation, but
|
|
* people do odd things sometimes.
|
|
*/
|
|
it( 'can re-add removed listener', () =>
|
|
{
|
|
var ev = 'foo',
|
|
called = false,
|
|
f = () => called = true;
|
|
|
|
stub.evDefineEvents( [ ev ] )
|
|
.on( ev, f )
|
|
.removeListener( ev, f )
|
|
.on( ev, f )
|
|
.evEmit( ev );
|
|
|
|
expect( called ).to.be.true;
|
|
} );
|
|
} );
|
|
} );
|
|
|
|
|
|
describe( 'listener metadata', () =>
|
|
{
|
|
/**
|
|
* It is important that each Evented instance store its listener
|
|
* metadata in a distinct field; otherwise, they would query
|
|
* each-other, which would produce conflicts if the events happen to
|
|
* have the same name (which would not be uncommon).
|
|
*/
|
|
it( 'is not accessible to other Evented instances', () =>
|
|
{
|
|
var ev = 'foo',
|
|
f = () => {};
|
|
|
|
// this would fail if data were shared because the system would
|
|
// consider f to have already been registered with event `foo'
|
|
[ stub, EvStub() ].forEach( s =>
|
|
s.evDefineEvents( [ ev ] )
|
|
.on( ev, f )
|
|
);
|
|
} );
|
|
} );
|
|
} );
|
|
|