More methods for NodeElement children manipulations

[jeffreyguo]

Added useful methods to get elements:

• getAllChildren()
• getDirectChildren()
• getFirstChild()
• getLastChild()
• getPreviousSiblings()
• getPreviousSibling()
• getNextSiblings()
• getNextSibling()
• findByName($name)
• findByTag($tag)

[aik099]

@jeffreyguo please use title and description fields of the issue/PR on GitHub appropriately. Do not write long texts in the title field.

[aik099]

I recommend you to synchronize GitHub username/e-mail used to login to GitHub and one set in your Git client. Without this you have 2 different avatars in your commits and your GitHub account.

[aik099]

Please correct indentation. I guess you're using TABs here (in in other places in this PR), which doesn't comply with PSR-2.

[aik099]

Actually most of the methods doesn't belong to NodeElement, but rather to Traversable class.

[jeffreyguo]

@aik099 I saw getParent() is in NodeElement.php, so I thought these getXXX methods could be placed here also.

[aik099]

Besides, what can be the use case for these methods? Considering that 1 element location operations takes time, then whole test suite can be really slow if you will traverse through element tree without actual knowing of what you're looking for.

[aik099]

Ah, I remembered one reason why find* methods are in NodeElement. The architecture (part) of a Mink is as follows:

For that reason, the prev/next and other majority of methods doesn't belong to TraversableElement since they don't apply to DocumentElement, that will inherit them. That's why they are placed in NodeElement.php.

P.S.
When you make a change in commits, then please write a comment about it, because GitHub doesn't send notifications when just commit changes.

[jeffreyguo]

New commit [c499b97]: Added replacement %nameMatch% for new method findByName and updated comment's format

[jeffreyguo]

New commit [0f20bfe]: Corrected the element name for nameselector name test

[jeffreyguo]

New commit [d832fd6]: Updated expected result from 1 to 11 for name test and passed

[jeffreyguo]

New commit [ef96fdb]: Updated name selector for partial search

[aik099]

Now it looks good. What I wonder is what can be the application of these methods in real life?

Mink is supposed to help in acceptance/functional testing. I've never seen, that somebody would do that massive element traversal (e.g. getChildren method) or similar ever.

[jeffreyguo]

Good question.

For automated testing, object identification is the most important thing. Sometimes there is no id, no name, and no one attribute can be relied on. At this case, relative path is useful, we can get an object by identifing its parent/sibling firstly, that's why getFirstchild()/getLastChild/getPreviousSibling()/getNextSibling() here.

With regard to getAllChildren(), it's useful in web Table test, e.g. get all cells in a table row.

[aik099]

I see. I haven't tested tables myself. Usually I place ID/class all over the place to be able to locate elements easily.

[stof]

findAll can never return null.

and it should be NodeElement[] or self[], not static[]. If you extend the NodeElement class, the elements returned here will not use the child class (findAll() always returns a list of NodeElement instances)

[stof]

these new methods should be covered by tests (both unit tests running in this repo testsuite, and functional tests running in the driver testsuite IMO)