docs: add section on how to test UI

[abdulshaikh55]

closes #358

Also write tests for collapse borders?

[joshka]

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.

[abdulshaikh55]

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.

[joshka]

• 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 calling some_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)

[joshka]

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.

ratatui-website/src/content/docs/tutorials/counter-app/error-handling/index.md

Line 190 in c4ae99e

```text collapse={8-27}

)

[abdulshaikh55]

Instead of this

You want the code to be written in code file instead of the code written in grave accent(`) am I right?

[joshka]

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.

[abdulshaikh55]

Based on the comments, these are the things I should do:

• Write the function and its test on the same page.
• Write the code in the code/ section.
• Write the tests without using TestBackend().
• Specify where to use TestBackend().
• Use widget test modules as reference (layout.rs).

Please tell me if I'm missing something @joshka.

[joshka]

Based on the comments, these are the things I should do:

* [ ]  Write the function and its test on the same page.

* [ ]  Write the code in the [`code/`](https://github.com/abdulshaikh55/website/tree/main/code) section.

* [ ]  Write the tests without using `TestBackend()`.

* [ ]  Specify where to use `TestBackend()`.

* [ ]  Use widget test modules as reference ([layout.rs](https://github.com/ratatui-org/ratatui/blob/8e68db9e2f57fcbf7cb5140006bbbd4dd80bf907/src/layout/rect/iter.rs#L116)).

Please tell me if I'm missing something @joshka.

Sounds about right - the first item is probably more like:

• Write the article in a way that presents the context or problem upfront and then the solution(s) to that problem

For more on the theory about what we're aiming for with the how-to sections see https://diataxis.fr/how-to-guides/

• https://ratatui.rs/how-to/render/overwrite-regions/ is a good example of what sort of level we're aiming at.
• https://ratatui.rs/how-to/layout/collapse-borders/ is another example, though is probably a bit too deep (and could use some headings)

[abdulshaikh55]

@joshka?

[joshka]

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)

1. Write a high level outline of an article for the ratatui.rs website (Ratatui is a fork of tui-rs a tui framework for rust). The article should be about how to test UIs and should include information about widgets, state, and other things specifically relevant to this task. The target reader is someone familiar with the Ratatui library, but unfamiliar with the techniques necessary to test their applications well. Ask additional clarifying questions necessary to help create the outline.

Before I create an outline for the article, I have a few clarifying questions to ensure I'm on the right track:

    What is the assumed level of testing knowledge of the target reader? Are they familiar with testing concepts in Rust, or will the article need to cover the basics of testing in Rust as well?
    Are there any specific testing frameworks or libraries that should be emphasized or avoided in the article? For example, should the article focus on using the built-in rust-test framework, or explore the use of other popular testing libraries like mockall or tokio?
    Are there any specific types of UI components or widgets in Ratatui that the article should focus on testing, or should the article provide a general approach that can be applied to various types of widgets?
    Are there any specific pain points or challenges that Ratatui users face when testing their UIs that the article should address?

2. Assumed level is beginner, we should not be testing unit tests, and should reference other resources like the ratatui book, where needed. Providing cargo commands / suggestions for helpful tools is good. Use just normal tests / rstest only. Most tests for rendering should create a widget, render it to an appropriate sized buffer and then check the contents of the buffer. This is an article targeting people writing applications using the widgets in Ratatui, their apps might contain widgets themselves (and it's useful to use the testing lens to encourage users to create widgets for parts of their app layout / display. Pain points that might be difficult to cover would be state (implemented by the statefulWidget trait, as well as the newer WidgetRef trait which allows widget reuse.

...

3. this should be less tutorial and more direct how-to (use the diataxis concepts for distinguishing these points)
4. move cargo test up, keep rstest around at the end, remove mockall, simplify the testing complex ui flows idea
5. incorporate section 2 cargo test into section 3 rendering

Here is the revised outline:

Title: Testing Ratatui UIs: A Practical Guide

I. Introduction

• Brief overview of the importance of testing in UI development
• Why testing is crucial for Ratatui applications
• Goals and scope of the article

II. Testing Rendering

• Principle: Verify that your widgets render correctly
• How-to: Create a test that renders a widget to a buffer and checks its contents
• Tips: Use a consistent buffer size, test different widget states
• Getting Started: Use cargo test to run and manage your tests
• Tips: Use cargo test features to improve testing efficiency

III. Testing State and Interactions

• Principle: Ensure that state changes and interactions work as expected
• How-to: Write tests that exercise state changes and user input
• Example: Testing a button's state change on click
• Tips: Use StatefulWidget and WidgetRef traits to manage state, test event handling and user input

IV. Testing UI Flows

• Principle: Verify that multiple widgets work together seamlessly
• How-to: Write tests that simulate user interactions and verify the resulting state
• Example: Testing a simple login flow
• Tips: Focus on testing key user interactions and state changes

V. Advanced Testing Techniques

• Principle: Use rstest to write concise and readable tests
• How-to: Use rstest features to improve test readability and maintainability
• Tips: Explore rstest features to improve your testing workflow

VI. Conclusion

• Recap of key takeaways for testing Ratatui UIs
• Final tips and resources for continued testing and improvement