-
Notifications
You must be signed in to change notification settings - Fork 71
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
docs: add section on how to test UI #489
Conversation
|
||
While the writing the test, keep this in mind: | ||
1. Since the direction of layout was `Vertical` (|), only the height of the subsequent `Rect`s and `y` intercept will be affected. | ||
2. Terminal can be rendered on a test backend. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
It's worth noting that tests written without the test backend tend to be shorter and more useful. Consider re-writing this based on the idea that unit tests just using buffer / widgets are often more important than the integration tests as they don't have to create as much state to use.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I don't understand what you want me to do.
test written without the test backend tend to be shorter and more useful
You want me to write the code without the test backend?
unit tests just using buffer / widgets are often more important than the integration tests
Please elaborate.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
- Write tests similar to those found in the unit tests in the ratatui source code (the code that is found in each widget under the
mod tests
part). These generally don't use TestBackend (there are a few exceptions to this). They just render a single widget to the Buffer by callingsome_widget.render(buf.area, &mut buf)
and then checking the contents of the buffer. - A good test is generally simple. Code written with TestBackend has to create too many things to test a UI (Terminal, Backend, call draw with a closure, etc.). Code written with just a buffer needs just that one thing.
- Write some narrative about when to use this approach and when to use the TestBackend (it's only necessary when testing code that deals with the terminal functions / frames - most application code should be written as widgets and interact with the Buffer directly and not the frame)
1. Since the direction of layout was `Vertical` (|), only the height of the subsequent `Rect`s and `y` intercept will be affected. | ||
2. Terminal can be rendered on a test backend. | ||
3. Express the type of the variable so that you don't get confused when you get back to it later. | ||
4. Don't forget to add `use::rc::Rc` at the top of your file. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Instead of this put the source in a real project under the code/
folder and point the user at the exact code that is being used. You can also hide lines in the code block (see e.g. https://github.com/ratatui-org/ratatui-website/blob/c4ae99e6b24eb0326056d9fd55c3fa89cf4ea877/src/content/docs/tutorials/counter-app/error-handling/index.md?plain=1#L190)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Instead of this
You want the code to be written in code
file instead of the code written in grave accent(`) am I right?
I think you may find it helpful to review / read some more unit tests across the ratatui source code. Start with https://github.com/ratatui-org/ratatui/blob/main/src/widgets/tabs.rs#L334 and take a bit of a random look at the other widgets. There's a few different styles in play depending on the age of the code, so you might have to think about what makes a good test / bad test. |
Based on the comments, these are the things I should do:
Please tell me if I'm missing something @joshka. |
Sounds about right - the first item is probably more like:
For more on the theory about what we're aiming for with the how-to sections see https://diataxis.fr/how-to-guides/
|
This PR is a bit shallow to merge just yet. I slapped a some of word vomit into LLama 3-70b to get an idea of what might be useful to write. I'd want to see some stuff around sections 1-2 at a minimum (perhaps 3), and we can add on the rest later. Use this as a guide / ideas if you want, it doesn't have to be exactly this. But it does have to test actual Ratatui related concepts (particularly those seen in apps). This is not a general unit testing tutorial, it's more specific to apps / widgets / etc. The text should be more than just presenting code to copy, it needs to describe why, how, what. If you haven't already, you might need to spend some time creating a real Ratatui application and seeing what problems you actually encounter when writing tests for the UI. My inputs (useful if you want to understand the context of what we're looking for)
...
Here is the revised outline: Title: Testing Ratatui UIs: A Practical Guide I. Introduction
II. Testing Rendering
III. Testing State and Interactions
IV. Testing UI Flows
V. Advanced Testing Techniques
VI. Conclusion
|
closes #358
Also write tests for collapse borders?