210 lines
7.3 KiB
JavaScript
210 lines
7.3 KiB
JavaScript
/**
|
|
* Tests interface interoperability with vanilla ECMAScript
|
|
*
|
|
* Copyright (C) 2014 Free Software Foundation, Inc.
|
|
*
|
|
* This file is part of GNU ease.js.
|
|
*
|
|
* GNU ease.js 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/>.
|
|
*/
|
|
|
|
require( 'common' ).testCase(
|
|
{
|
|
caseSetUp: function()
|
|
{
|
|
this.Sut = this.require( 'interface' );
|
|
this.Class = this.require( 'class' );
|
|
|
|
this.I = this.Sut(
|
|
{
|
|
foo: [ 'a', 'b' ],
|
|
bar: [ 'a' ],
|
|
} );
|
|
|
|
this.assertICompat = function( I, inst )
|
|
{
|
|
this.assertOk( I.isCompatible( inst ) );
|
|
this.assertOk( this.Sut.isInstanceOf( I, inst ) );
|
|
};
|
|
|
|
this.assertNotICompat = function( I, inst )
|
|
{
|
|
this.assertOk( !I.isCompatible( inst ) );
|
|
this.assertOk( !this.Sut.isInstanceOf( I, inst ) );
|
|
};
|
|
},
|
|
|
|
|
|
/**
|
|
* Not all developers will wish to use ease.js, even if the library they
|
|
* are interfacing with does. In the case of interfaces, this isn't
|
|
* particularity important. To understand why, consider the three main
|
|
* reasons why interfaces would be used: (1) to ensure that an object
|
|
* conforms to a defined API; (2) to permit polymorphism; and (3) to
|
|
* denote intent of use, meaning that even though a Basketball and Gun
|
|
* may both implement a `shoot' method, they are not intended to be used
|
|
* in the same context, even if both of them can be `shot'.
|
|
*
|
|
* Prototypes in JavaScript, without aid of a static analysis tool,
|
|
* generally rely on duck typing to enforce interfaces. In this sense,
|
|
* (3) can be sacrificed for the sake of interop but it's still
|
|
* important when working with ease.js classes). Since (2) follows as a
|
|
* consequence of (1), we need only a way to ensure that the API of the
|
|
* prototype is compatible with the named interface. In ease.js, this is
|
|
* is quick: the implemented interfaces are cached. With prototypes,
|
|
* even though it's not as efficient, we can still check that each of
|
|
* the methods named in the interface exist and are compatible (have the
|
|
* proper number of arguments).
|
|
*
|
|
* This has two powerful consequences: (1) external code can interface
|
|
* with ease.js without having to buy into its class/interface system;
|
|
* and (2) interfaces can be created to represent existing
|
|
* objects/prototypes (e.g. W3C DOM APIs).
|
|
*/
|
|
'Prototype instances and objects can conform to interfaces': function()
|
|
{
|
|
// conforming prototype
|
|
function P() {};
|
|
P.prototype = {
|
|
foo: function( a, b ) {},
|
|
bar: function( a ) {},
|
|
};
|
|
|
|
var p = new P();
|
|
|
|
// instance should therefore be conforming
|
|
this.assertICompat( this.I, p );
|
|
|
|
// ah but why stop there? (note that this implies that *any* object,
|
|
// prototype or not, can conform to an interface)
|
|
this.assertICompat( this.I, P.prototype );
|
|
},
|
|
|
|
|
|
/**
|
|
* The entire point of interfaces is to ensure that a specific API is in
|
|
* place; methods are the core component of this.
|
|
*/
|
|
'Objects missing methods are non-conforming': function()
|
|
{
|
|
// missing method
|
|
function P() {};
|
|
P.prototype = {
|
|
foo: function( a, b ) {},
|
|
};
|
|
|
|
this.assertNotICompat( this.I, new P() );
|
|
this.assertNotICompat( this.I, P.prototype );
|
|
},
|
|
|
|
|
|
/**
|
|
* ease.js enforces parameter count so that implementers are cognisant
|
|
* of the requirements of the API. We have two cases to consider here:
|
|
* (1) that an external prototype is attempting to conform to an ease.js
|
|
* interface; or (2) that an interface is being developed for an
|
|
* existing external prototype. In the former case, the user has control
|
|
* over the parameter list. In the latter case, the interface designer
|
|
* can design an interface that requires only the most common subset of
|
|
* parameters, or none at all.
|
|
*/
|
|
'Methods missing parameters are non-conforming': function()
|
|
{
|
|
// missing second param (at this point, we know prototype traversal
|
|
// works, so we will just use any 'ol object)
|
|
var obj = { foo: function( a ) {} },
|
|
I = this.Sut( { foo: [ 'a', 'b' ] } );
|
|
|
|
this.assertNotICompat( I, obj );
|
|
},
|
|
|
|
|
|
/**
|
|
* This test is consistent with ease.js' functionality.
|
|
*/
|
|
'Methods are still compatible with extra parameters': function()
|
|
{
|
|
// extra param is okay
|
|
var obj = { foo: function( a, b, c ) {} },
|
|
I = this.Sut( { foo: [ 'a', 'b' ] } );
|
|
|
|
this.assertICompat( I, obj );
|
|
},
|
|
|
|
|
|
/**
|
|
* This should go without explanation.
|
|
*/
|
|
'Interface methods must be implemented as functions': function()
|
|
{
|
|
// not a function
|
|
var obj = { foo: {} },
|
|
I = this.Sut( { foo: [] } );
|
|
|
|
this.assertNotICompat( I, obj );
|
|
},
|
|
|
|
|
|
/**
|
|
* Interfaces define only an API that must exist; it does not restrict a
|
|
* more rich API.
|
|
*/
|
|
'Additional methods do not trigger incompatibility': function()
|
|
{
|
|
// extra methods are okay
|
|
var obj = { foo: function() {}, bar: function() {} },
|
|
I = this.Sut( { foo: [] } );
|
|
|
|
this.assertICompat( I, obj );
|
|
},
|
|
|
|
|
|
/**
|
|
* When an object is instantiated from an ease.js class, it does not
|
|
* matter if the interface is compatible: in order to be considered an
|
|
* instance some interface I, the instance's type must implement I; in
|
|
* this sense, ease.js' interface typing is strict, allowing *intent* to
|
|
* be conveyed.
|
|
*
|
|
* An example of why this is important can be found in the
|
|
* interoperability section of the manual.
|
|
*/
|
|
'Objects can be compatible but not instances of interface': function()
|
|
{
|
|
// same API, different interface objects
|
|
var Ia = this.Sut( { foo: [] } ),
|
|
Ib = this.Sut( { foo: [] } );
|
|
|
|
var dfn = { foo: function() {} },
|
|
Ca = this.Class.implement( Ia ).extend( dfn ),
|
|
Cb = this.Class.implement( Ib ).extend( dfn );
|
|
|
|
var ia = Ca(),
|
|
ib = Cb();
|
|
|
|
// clearly the two are compatible, regardless of their type
|
|
this.assertOk( Ia.isCompatible( ia ) );
|
|
this.assertOk( Ia.isCompatible( ib ) );
|
|
this.assertOk( Ib.isCompatible( ia ) );
|
|
this.assertOk( Ib.isCompatible( ib ) );
|
|
|
|
// but ia is *not* an instance of Ib, nor ib of Ia
|
|
this.assertOk( this.Sut.isInstanceOf( Ia, ia ) );
|
|
this.assertOk( !this.Sut.isInstanceOf( Ia, ib ) );
|
|
this.assertOk( this.Sut.isInstanceOf( Ib, ib ) );
|
|
this.assertOk( !this.Sut.isInstanceOf( Ib, ia ) );
|
|
},
|
|
} );
|
|
|