[5.2] Add within() method to InteractWithPages

[sileence]

I have needed this several times when writing tests for complex markups.

This method allows to narrow the test assertions or actions to specific areas of the web page.

For example, you have 2 links with the same text in the same page, but you want to make sure you click the one inside the content area:

        <header>
            <a href="link1">Link</a>
        </header>
        <div class="container">
            <a href="link2">Link</a>
        </div>

    $this->within('.container', function () {
        $this->seeLink('Link')
                ->click('Link');
        });
    });

Same if you want to make sure you see several texts / elements within a certain area of the page (see tests in the commit).

[daylerees]

Pretty cool addition. Maybe in the tests check for what happens when the container doesn't exist.

[sileence]

@daylerees thank you and good point, it should throw an exception.

[taylorotwell]

Don't you technically need a subcrawler stack in case you have nested within calls?

[sileence]

@taylorotwell added support for nested within calls

[lucasmichot]

@var array maybe ?

[lucasmichot]

👍 That was fast !

[sileence]

@lucasmichot thank you. Docblocks fixed.

[GrahamCampbell]

Surely the change to that protected property is a massive breaking change for people?

[sileence]

@GrahamCampbell only if they are creating their own test methods. But let me use sub crawler again.

[GrahamCampbell]

Ping @crynobone.

[sileence]

Ok done, if someone is using the protected property $crawler directly, it will work like before. If someone wants to use within with custom test methods, they'd need to use getCrawler() instead :)

[taylorotwell]

Thanks. Can you PR some docs for this?

[sileence]

I'll do! Thank you @taylorotwell

[nowak-ninja]

Hey guys. I just noticed API says that within() method should return instance of $this but actually it doesn't so there is no way to continue with fluent interface after using within() method: https://github.com/laravel/framework/blob/5.2/src/Illuminate/Foundation/Testing/Concerns/InteractsWithPages.php#L213

[sileence]

@Flashek I'll solve that issue, thank you.

[sileence]

done #13200