1
0
Fork 0
easejs/test/Class/InteropTest.js

406 lines
13 KiB
JavaScript

/**
* Tests class interoperability with vanilla ECMAScript
*
* Copyright (C) 2014 Mike Gerwitz
*
* This file is part of GNU ease.js.
*
* 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/>.
*
* Note that these tests all use the `new' keyword for instantiating
* classes, even though it is not required with ease.js; this is both for
* historical reasons (when `new' was required during early development) and
* because we are not testing (and do want to depend upon) that feature.
*/
require( 'common' ).testCase(
{
caseSetUp: function()
{
this.Class = this.require( 'class' );
},
/**
* While this may seem at odds with ease.js' philosophy (because ease.js
* methods are *not* virtual by default), we do not have much choice in
* the matter: JavaScript is very lax and does not offer a way to
* declare something as virtual or otherwise. Given that, we have to
* choose between implicit virtual methods, or never allowing the user
* to override methods inherited from a prototype. The latter is not a
* wise choice, since there would be no way to change that behavior.
*
* Of course, if such a distinction were important, a wrapper class
* could be created that simply extends the prototype, marks methods
* virtual as appropriate, and retain only that reference for use from
* that point forward.
*/
'Methods inherited from a prototype are implicitly virtual': function()
{
var expected = {};
var P = function()
{
this.foo = function()
{
return null;
};
}
var Class = this.Class,
inst;
// if an error is thrown here, then we're probably not virtual
this.assertDoesNotThrow( function()
{
inst = Class.extend( P,
{
'override foo': function()
{
return expected;
}
} )();
} );
// the sky is falling if the above worked but this didn't
this.assertStrictEqual( inst.foo(), expected );
},
/**
* Complement to the above test.
*/
'Prototype method overrides must provide override keyword': function()
{
var P = function()
{
this.foo = function() {};
};
var Class = this.Class;
this.assertThrows( function()
{
Class.extend( P,
{
// missing override keyword
foo: function() {},
} );
} );
},
/**
* This was a subtle bug that creeped up in a class that was derived
* from a prototype: the prototype was setting its property values
* (which are of course public), which the class was also manipulating.
* Unfortunately, the class was manipulating a property of a same name
* on the private visibility object, whereas the prototype instance was
* manipulating it on the public. Therefore, the value of the property
* varied depending on whether you asked the class instance or the
* prototype instance that it inherited. Yikes.
*
* The root issue of this was even more subtle: the parent method (that
* does the manipulation) was invoked, meaning that it was executed
* within the context of the private visibility object, which is what
* caused the issue. However, this issue is still valid regardless of
* whether a parent method is called.
*
* Mitigating this is difficult, so we settle for a combination of good
* guessing and user education. We assume that all non-function fields
* set on the object (its own fields---not the prototype chain) by the
* constructor are public and therefore need to be proxied, and so
* implicitly declare them as such. Any remaining properties that are
* set on the object (e.g. set by methods but not initialized in the
* ctor) will need to be manually handled by declaring them as public in
* the class. We test the first case here.
*/
'Recognizes and proxies prototype properties as public': function()
{
var expected = 'baz',
expected2 = 'buzz';
// ctor initializes a single property, which is clearly public (as
// all fields on an object are)
var P = function()
{
this.foo = 'bar';
this.updateFoo = function( val )
{
this.foo = val;
};
};
var inst = this.Class.extend( P,
{
// since updateField is invoked within the context of the
// instance's private visibility object (unless falling back),
// we need to ensure that the set of foo is properly proxied
// back to the public property
'override updateFoo': function( val )
{
// consider that we're now invoking the parent updateFoo
// within the context of the private visibility object,
// *not* the public visibility object that it is accustomed
// to
this.__super( val );
return this;
},
ownUpdateFoo: function( val )
{
this.foo = val;
return this;
}
} )();
// if detection failed, then the value of foo will still be "bar"
this.assertEqual( inst.ownUpdateFoo( expected ).foo, expected );
// another interesting case; they should be mutual, but it's still
// worth demonstrating (see docblock comments)
this.assertEqual( inst.updateFoo( expected2 ).foo, expected2 );
},
/**
* This demonstrates what happens if ease.js is not aware of a
* particular property. This test ensures that the result is as
* expected.
*/
'Does not recognize non-ctor-initialized properties as public':
function()
{
var expected = 'bar';
var P = function()
{
this.init = function( val )
{
// this was not initialized in the ctor
this.foo = val;
return this;
};
};
var inst = this.Class.extend( P,
{
rmfoo: function()
{
// this is not proxied
this.foo = undefined;
return this;
},
getFoo: function()
{
return this.foo;
}
} )();
// the public foo and the foo visible inside the class are two
// different references, so rmfoo() will have had no effect on the
// public API
this.assertEqual(
inst.init( expected ).rmfoo().foo,
expected
);
// but it will be visible internally
this.assertEqual( inst.getFoo(), undefined );
},
/**
* In the case where ease.js is unable to do so automatically, we should
* be able to correct the proxy situation ourselves. This is where the
* aforementioned "education" part comes in; it will be documented in
* the manual.
*/
'Declaring non-ctor-initialized properties as public resolves proxy':
function()
{
var expected = 'bar';
var P = function()
{
this.init = function()
{
// this was not initialized in the ctor
this.foo = null;
return this;
};
};
var inst = this.Class.extend( P,
{
// the magic
'public foo': null,
setFoo: function( val )
{
this.foo = val;
return this;
}
} )();
this.assertEqual( inst.init().setFoo( expected ).foo, expected );
},
/**
* While this should follow as a conseuqence of the above, let's be
* certain, since it would re-introduce the problems that we are trying
* to avoid (not to mention it'd be inconsistent with OOP conventions).
*/
'Cannot de-escalate visibility of prototype properties': function()
{
var P = function() { this.foo = 'bar'; };
var Class = this.Class;
this.assertThrows( function()
{
Class.extend( P,
{
// de-escalate from public to protected
'protected foo': '',
} );
} );
},
/**
* This check is probably not necessary, but is added to prevent any
* potential regressions. This ensures that public methods on the
* prototype will always return the public visibility object---and they
* would anyway, since that's the context in which they are invoked
* through the public API.
*
* The only other concern is that when they are invoked by other ease.js
* methods, then they are passed the private member object as the
* context. In this case, however, the return value is passed back to
* the caller (the ease.js method), which properly handles returning the
* public member object instead.
*/
'Returning `this` from prototype method yields public obj': function()
{
var P = function()
{
// when invoked by an ease.js method, is passed private member
// object
this.pub = function() { return this; }
};
var inst = this.Class.extend( P, {} )();
// should return itself; we should not have modified that behavior
this.assertStrictEqual( inst.pub(), inst );
},
/**
* When prototypally extending a class, it is not wise to invoke the
* constructor (just like ease.js does not invoke the constructor of
* subtypes until the supertype is instantiated), as the constructor may
* validate its arguments, or may even have side-effects. Expose this
* internal deferral functionality for our prototypal friends.
*
* It is incredibly unwise to use this function purely to circumvent the
* constructor, as classes will use the constructor to ensure that the
* inststance is in a consistent and expected state.
*
* This may also have its uses for stubbing/mocking.
*/
'Can defer invoking __construct': function()
{
var expected = {};
var C = this.Class(
{
__construct: function()
{
throw Error( "__construct called!" );
},
foo: function() { return expected; },
} );
var inst;
this.assertDoesNotThrow( function()
{
inst = C.asPrototype();
} );
// should have instantiated C without invoking its constructor
this.assertOk( this.Class.isA( C, inst ) );
// we should be able to invoke methods even though the ctor has not
// yet run
this.assertStrictEqual( expected, inst.foo() );
},
/**
* Ensure that the prototype is able to invoke the deferred constructor.
* Let's hope they actually do. This should properly bind the context to
* whatever was provided; it should not be overridden. But see the test
* case below.
*/
'Can invoke constructor within context of prototypal subtype':
function()
{
var expected = {};
var C = this.Class(
{
foo: null,
__construct: function() { this.foo = expected; },
} );
function SubC() { this.__construct.call( this ); }
SubC.prototype = C.asPrototype();
this.assertStrictEqual(
( new SubC() ).foo,
expected
);
},
/**
* Despite being used as part of a prototype, it's important that
* ease.js' context switching between visibility objects remains active.
*/
'Deferred constructor still has access to private context': function()
{
var expected = {};
var C = this.Class(
{
'private _foo': null,
__construct: function() { this._foo = expected; },
getFoo: function() { return this._foo },
} );
function SubC() { this.__construct.call( this ); }
SubC.prototype = C.asPrototype();
this.assertStrictEqual(
( new SubC() ).getFoo(),
expected
);
},
} );