Nested modules

[leobalter]

Replaces/Closes #800
Closes #543

This PR closes #800 with extra additions to the PR to assure a good landing of nested modules.

We might want to observe the issues listed at #858 and add extra commits

cc @gibson042

[leobalter]

@jzaefferer @gibson042 I need opinions on this test.

[gibson042]

Seems ok to me. The interaction itself sucks, but the test captures it well.

[leobalter]

@gibson042 I made two commits to include arguments on the contained modules callback. I appreciate if you review and criticize.

cc @jzaefferer

[leobalter]

This is even better on ES6:

QUnit.module( "foo", ( test, { beforeEach, afterEach } ) => {
  beforeEach: () => {
    ...
  };

  ...
});

Also, a funny fact:

const describe = QUnit.module;

describe( "wat", it => {
  it( "works", ( { ok } ) => {
    ok( true, "omg" );
  });
});

[gibson042]

I'm assuming these .js_ files are accidental additions.

[leobalter]

caught in a git add .

[leobalter]

57527a3

[gibson042]

I made two commits to include arguments on the contained modules callback. I appreciate if you review and criticize.

I'm not sure about these particular parameters. As I've noted elsewhere, I'd like module and test callback signatures to look as similar as possible. But further than that, I'd like module callbacks to be straightforward. It seems to me that data passed in to them—including as this—should be entirely sufficient to define submodules/tests/etc., but hopefully not exceed that.

In my opinion, it's better to pass nothing at all now than it is to guess wrong about the signature. Since this iteration still requires access to the global QUnit for some operations (e.g., submodules), I'd actually prefer an argument-free executeNow() for this PR, saving context/arguments for later as discussed. For example, a possible future that would be precluded by passing test now:

QUnit.module("outer", function( outerModule ) {
    // environment (prototype for test/submodule context)
    this.outer = true;
    this.outerBefore = 0;

    // test before/after
    outerModule.test.beforeEach(function() {
        this.outerBefore++;
    });

    // tests
    outerModule.test("foo", function( assert ) {
        assert.equal(this.outerBefore, 1, "beforeEach updated environment");
    });
    outerModule.test("bar", function( assert ) {
        assert.equal(this.outerBefore, 1, "sibling tests don't share environments");
    });

    // submodules
    outerModule.module("inner", function( innerModule ) {
        // environment (inherits from parent)
        this.inner = true;

        function assertEnvironment( assert, before ) {
            assert.ok(this.outer, "outer module initialized environment");
            assert.ok("outerBefore" in this, "outer module beforeEach updated environment");
            assert.equal(this.outerBefore, 1, "submodules don't share environments");
            assert.ok(this.inner, "inner module initialized environment");
            if ( before ) {
                return;
            }
            assert.ok(this.innerBefore, "inner module beforeEach updated environment");
            assert.ok(this.tested, "test updated environment");
        }

        // test before/after
        innerModule.test.beforeEach(function( assert ) {
            this.innerBefore = true;
            assertEnvironment.call( this, assert, true );
        });
        innerModule.test.afterEach(function( assert ) {
            assertEnvironment.call( this, assert );
        });

        // tests
        innerModule.test("bar", function( assert ) {
            this.tested = true;
            assertEnvironment.call( this, assert );
        });
    });
});

[leobalter]

QUnit.module("outer", function( outerModule ) {
    // environment (prototype for test/submodule context)
    this.outer = true;
    this.outerBefore = 0;

    // test before/after
    outerModule.test.beforeEach(function() {
        this.outerBefore++;
    });

    // tests
    outerModule.test("foo", function( assert ) {
        assert.equal(this.outerBefore, 1, "beforeEach updated environment");
    });
    outerModule.test("bar", function( assert ) {
        assert.equal(this.outerBefore, 1, "sibling tests don't share environments");
    });

    ...

These this.outerBefore tests seems very confusing to me. I can understand the point here but I'm uncomfortable with it so far.

---

I'm not sure about these particular parameters.

And reviewing my code I'll indeed remove the first test argument.

And following your own example, I would stick with the first argument being an object with the hooks methods and it can later being extended. This way:

QUnit.module("outer", function( outerModule ) {
    ...
    outerModule.beforeEach(function() {
        ...
    });

    outerModule.afterEach(function() {
        ...
    });

but also, later in further additions:

QUnit.module("outer", function( t ) {
    t.beforeEach(function() {
        ...
    });
    t.test( "the test method", function( assert ) {
        ...
    });
});

and using ES6:

QUnit.module("outer", ( { beforeEach } ) => {
    beforeEach(function() {
        ...
    });
    QUnit.test( "the test method", function( assert ) {
        ...
    });
});

The reason to start with beforeEach and afterEach methods is to avoid calling modules with three arguments, where the hooks object is already big enough:

QUnit.module( "outer", {
        beforeEach: function( assert ) {
            ...
        },
        afterEach: function( assert ) {
            ...
        }
    },
    function( t ) {
        QUnit.test( "the test method", function( assert ) {
            ...
        });
    }
);

[leobalter]

@gibson042: both 29f5b84 and 53778e3 has the shared this based on your example.

The this object is only propagated from the outer to the inner scopes without duplicating the test hooks.

I also removed the test argument as you can see on the fixup commits.

We may then extend the module callback argument to include test later. I want to at least bring the shared this and the hooks when landing the nested modules.

[gibson042]

I think Object.create-style inheritance would be better, but am willing to shelve that for now.

[leobalter]

I would love to do this. We still support ES3 until QUnit 2.0.0

[gibson042]

Arbitrary inheritance is possible in ES3, too:

var createObject = (function( Base ) {
    return function( prototype ) {
        Base.prototype = prototype;
        return new Base();
    };
})( Function() );
…
env = createObject( parentModule.testEnvironment );

The above is similar to a stripped-down version of lodash's baseCreate, but you could easily go all the way to _.create if you want this part to look like module.testEnvironment = createObject( parentModule.testEnvironment, testEnvironment ) (removing the need for a separate extend).

[leobalter]

This is cool, but I would leave this improvement for later as this requires a whole new review. Does it works for you?

[gibson042]

Yep.

[gibson042]

👍 The single callback argument is a decent (if limited) module stand-in and has good room for growth, and you are absolutely right about this:

The reason to start with beforeEach and afterEach methods is to avoid calling modules with three arguments, where the hooks object is already big enough

Let's hope that module and test follow suit, so that we can eventually get to a point where module callbacks need nothing other than what's passed directly to them, just like current test callbacks.

[gibson042]

I think this is good to go; module environment inheritance can be addressed with a subsequent issue & PR.

[leobalter]

Opened #869 to follow up with this.