Support for Drupal 7 is ending on 5 January 2025—it’s time to migrate to Drupal 10! Learn about the many benefits of Drupal 10 and find migration tools in our resource center.Problem/Motivation
While I was trying to figure out #1791970: Optionally detect tar.* as extension instead of * on views file extension field handler I noticed the procedure to make views unit test is a little tricky, and some maintainers agreed with me about that.
So, what I think we should be documented:
- It is recommmended to use a custom module to test views handlers.
- Those modules should live on module's tests/modules directory.
- It is recommmended to define new views instead of reusing the ones provided by views and change them at runtime, unless there is a good reason behind that.
- To have the defined view loaded you need to:
- add the view machine name on the
$testViewsdata member declaration - store the exported view on test module's
test_viewsdirectory with file nameviews.view.<machine_name>.yml - Implement
setUpand callViewTestData::importTestViews()passing the module containing the default test view.
- add the view machine name on the
- It is recommended define the test calss on
Drupal\file\Tests\Views namespace. - Mention how to use
dataSet()andviewsData(). - Maybe an basic example (an extension of
Drupal\views\Tests\BasicTest?).
Proposed resolution
Let's document it!
Remaining tasks
- Decide where to document it. Current propposals:
- at
Drupal\views\Tests\ViewUnitTestBase - at
Drupal\views\Tests\BasicTest
- at
User interface changes
None.
API changes
None.
Related Issues
| Comment | File | Size | Author |
|---|---|---|---|
| #7 | 2000058-7.patch | 1.44 KB | marvil07 |
| #7 | interdiff.txt | 1.27 KB | marvil07 |
| #2 | 0001-Issue-2000058-by-marvil07-Documents-how-to-make-view.patch | 1.82 KB | marvil07 |
Comments
Comment #1
jhodgdonUm. Probably the best place to document these types of things would actually be somewhere inside
http://drupal.org/simpletest
Then you could point to that documentation from the base class(es) for Views tests.
I don't think it's a good idea to put a bunch of tutorial documentation on how to write tests into the API documentation.
Comment #2
marvil07 CreditAttribution: marvil07 commentedJust in case it makes sense to have it on code, here a start patch.
IMHO it's better to have it in code, since I would say most people writing views tests will be looking at code documentations instead of handbook pages.
Comment #3
dawehnerGreat stuff, thank you!
What would be also very helpful: Provide a @see to an easy example.
Comment #4
marvil07 CreditAttribution: marvil07 commented@dawehner: yes, that makes sense, I would say #1791970: Optionally detect tar.* as extension instead of * on views file extension field handler is simple enough to serve as example, but if there is another one already in core, I'll be happy to add it.
Comment #5
dawehnerThat's a good idea.
Comment #6
jhodgdonThat documentation does indeed look like a very useful addition to the API docs! +1. Is that really all you need to do for Views to detect your test view and make it available? If so, cool, and definitely a good idea to document it this way.
One typo I noticed:
+ * For new views unit tests tests defined on a external module:
The word "tests" is repeated. Also, what's an "external" module? Do you just mean "a module that isn't views itself"? If so, I think I would say "To make a Views unit test outside the Views module:" or something like that.
Comment #7
marvil07 CreditAttribution: marvil07 commented@jhodgdon: Yes, that's all needed steps. Thanks for the correction, that's what I tried to said.
Here a new patch with that and the new
@see.Comment #8
jhodgdonThat looks pretty good to me! The only question I had was whether, technically, setUp() would be implementing something (from an interface) or overriding something (from a base class)? Other than that, assuming someone from the Views team can verify that the documentation is accurate, I think it's ready to go.
And maybe instead of saying "Define the test module view" you might say "Define any views needed in your tests"?
Comment #9
damiankloip CreditAttribution: damiankloip commentedLooking pretty good!
This should maybe also contain the prefix. You never know what people will assume in some cases.
Nice. BasicTest is a good example implementation.
Comment #10
jhodgdonRE #9 - what prefix? Maybe the documentation should say something like "Choose a machine name for your view that is prefixed by your module's machine name"?
Comment #11
damiankloip CreditAttribution: damiankloip commentedI mean that it should state that the tests directory lives in a modules directory. With a name like tests and also the module namespace, this might not be obvious to your average developer.
Comment #12
jhodgdonUm... The documentation already starts out by saying "if you want to create a test for Views that is not inside the Views module", which implies it is in some other module? And I don't think we need to document how to do PSR-0 here... Maybe I'm missing something that you're trying to get across though?
Comment #13
jhodgdonI took a look at this again today... I think this spot could use a comma or the word "in" ("passing in") or something -- it's a bit hard to read:
I am still not sure that we need any clarification to address #9, since we don't want to document how to make tests in general or how to do PSR-0 here. Thoughts?
Comment #13.0
jhodgdonfix html
Comment #25
quietone CreditAttribution: quietone at PreviousNext commentedThere are now many views tests in core outside of the views module itself. These provide plenty of examples to use when writing a test. I am not aware of other documentation in core that explains how to write tests, it certainly was not added for the migration system.
As far as I know it is established practice to look at existing tests as examples when writing new tests. That has the advantage of being up to date, whereas the documentation can fall behind. Therefor, I am setting this as won't fix. If you disagree, re-open and explain.
Thanks