Proposal: Testing and Debugging Project

[adriatic]

NOTE: This project builds on top of the two years old document on Debugging RedwoodJS Applications

---

I would like to create a RW companion tutorial presenting chapters on testing and debugging - in the context of Tutorial I and Tutorial II. It is hosted on Netlify and created with Docusaurus 2.0, so that eventually all or some of its content could be moved to original RWJS Docs.

Expanding the collection of online docs to be written by members of RWJS community is likely the most important task following the RWJS initial release. This assessment was recently confirmed in discussion with a customer, who claimed that this guide is the only information missing at this time

Caveat: This project is the first of its kind, as it expects that it will be staffed by Redwood contributors (not core team members). As such it is being run in front of everyone eyes, starting with the project definition. It could never reach its implementation if there are not sufficient number of volunteers.

Coming next:

1. Top level definition of the tandem (testing and debugging) guide will be presented below and the content of all people’s feedback will be transferred into the repository tandem. At the moment, this repo has no relevant info to share (other than a few experiments), so I will announce when it will be ready for some real work. In the meantime, I expect to conduct all discussions in this category of RWJS Discourse app.

2. In order to minimize any unnecessary conflicts with regular RWJS docs, we will be using the before mentioned tandem for design and development of this collection of guides. The guides will be deployed on Netlify using Docusaurus 2.0, so that eventually all or some of its content could be moved to original RWJS Docs. Note: at the moment tandem contains the code for our private instance of Docusaurus 2.0 container.

3. The conclusions from this category will be maintained in issues collection - visible to everyone, regardless of whether you plan to be active in this project or not.

I plan to continue expanding this project’s information asynchronously from community feedback (as long as it does not break the rules of polite behavior (not to create the perception that I do not care about community members feedback )) I will stop writing this at the moment we reach the consensus that defining process yields enough information to start the “real work”.

Participation Poll

• I am interested in participating in Testing and Debugging project
• I am interested but have no free time to participate
• I want to wait until I see the more details of this project

Working status (updated daily)

3/27/2022 - creation of the deployed version of the docusaurus based docs app (need two more days to finish. Very curious people can check the first draft of the skeleton app at https://charming-phoenix-676bab.netlify.app/.

3/28/2022 - same as above - just one day closer to the first draft of the docs app content

3/30/2022 - In order to prevent any collisions with the ongoing activity related to version 1.0 release, I decided to create a temporary home for this “Testing and Debugging” docs (code named tandem ), - a Docusaurus 2.0 website at https://rw-community.org I acquired this domain and am finishing building this website - the content stems from the Docusaurus’ own sample site, data that I still need to change, in accordance with my initial vision what this content needs to be.

4/1/2022 Missed a day for updating this “diary” - fighting deployment problem with the docusaurus tandem (Testing and Debugging) application

4/6/2022 It makes little sense to write an update without having to show anything there are gaps in this diary. Today I can show the first version of the website hosting docusaurus based documents we will write next. (https://rw-community.org)

This website has no data yet - it is just the skeleton. Once I set the initial content, this information will be replicated here - in the Top level definition of the tandem project. At that time, we can start the discussion about the initial content of this project.

Note that the proposal for the project 🌲 Redwood Logging - Ideas? has similar structure and ideas, using different methods and technologies to assist developing Redwood apps. To simplify eventual merging of that information with tandem project, I will define this project using a similar layout.

---

---

[adriatic]

Top level definition of the tandem project

Executive Summary:

create a companion document to the RedwoodJS Tutorial which explains the concepts of testing and debugging using the Tutorial application as the context.

Introduction

This project expands on existing chapters in RedwoodJS Docs:

• Logger
• Mocking GraphQL requests
• Testing
• Debugging

all of which are essential parts of developer workflow, by adding the description of the concept of Debugging and demonstrating the use of all these tools and methods in the context of creating the RedwoodJS Tutorial application.

This application is chosen as the context, because is really well explained in the Tutorial and is complex enough to expand the examples already presented in the Tutorial like Building a Test Runner. Similarly, the Debugging chapter of tandem will expand on information presented in Windows Development Setup and Windows Subsystem for Linux Setup

Tools

• Chrome DevTools
• VScode
• Storybook
• Webstorm
• Wallaby
• Jest

Actions

Note that this proposal addresses Redwood community members (while it does not preclude Redwood Core Team members, who are interested in helping document the application development use of the above listed tools in the context of Redwood app development. It is not expected that authors of this proposal write all these documents (contents of this project) – the majority of that effort falls on the community members volunteering to participate.

Before expecting comments from Redwood Community and anyone else who wants to supply them, we will write several documents to suggest the content and the style

Once the feedback is complete, we will merge this with the current content and present this data as the real definition of this project.

---

Status on 04/09/2022

Introducing the first draft of RedwoodJS Community Library project described here. In order to minimize the size of this Discourse discussion as well as impact on ongoing work of the core team, the application itself lived on my own repo.

In order to facilitate the discussions on this project, while providing enough content, I will start “filling” the testing chapter. The fact that so far there is one vote expressing interest is not really relevant as there is no information on this project available yet - other than this project expects RW contributors write parts of it.

Status on 04/013/2022

Reached the level where this project would benefit from comments by core team members, which may care about the aims of it. Please check:

• overall introduction
• tools introduction
• chrome devtools
• testing introduction

The plan is to solicit members of rw community to fill on whatever is not written in this site, so it is critically important to ensure that this project “has the back” of the core team.

Status on 04/014/2022

It is difficult to create this project, at the time when parts of it appear in various core team’s members projects. In other words, I was hoping that there will be some minimal coordination that would help not addressing the same thing more than once. So, part of my daily task is to try to read all current updates and make references in sections where a pointer to some currently published just appeared.

The purpose of this project is to enable RW “customers” (community members that use RW and are not core team members) to write docs on how to use RedwoodJS. At the same time it is unlikely that this site that extends the official RW docs site, will be of much use without the critical comments and eventual adoption from core team members.

Current scope of the application (not all chapters contain data - as something needs to created by the community members ), shown below:

[thedavid]

I’m really excited to see this happen. Thanks for taking it on, @adriatic

[adriatic]

Status on 04/15/2022

Raising an important issue for which I have solution - by sharing it here, I hope to find a better solution. I want to cover both testing and debugging of a specific copy of the Tutorial as described in the README section of the main branch of the tandem-samples repository - which is a “sister site” to the RW Community Library site.

The solution for providing the tutorial application “hacked” for all cases of testing and debugging as branches of the tandem-samples site obviously expects that the user has to know how to “extract” the needed branch. The instructions related to that branch can be viewed by pointing the browser to GitHub - adriatic/tandem-samples.

[adriatic]

Status on 04/17/2022

Reached the point time, when other RW fans could evaluate the app at https://rw-community.org/ (only in the sense that the app’s skeleton indicates the planned coverage) and point out the missing or not necessary information.

The main feature is to use the finished Redwood Tutorial application as the “object” used to show testing and debugging practice.

Another novelty is to engage Redwood community members to author the missing articles in the Tandem (Testing and Debugging - name that requires a bit of licentia poetica). We hope that the reaction from the community will allow the core team to work under less stressful circumstances)

[ajoslin103]

Looks good so far, I like the concept - thanks! I’ve posted a PR to add RW Linkage to the top bar.

I think it needs a Search Box, but I’m not sure how to make that work in what seems like a markup site? (apologies if I’m missing something basic here)

It’s very cool that PRs result in Preview deployment – that’s excellent! Do those get torn down automatically when the PR is closed? The email it sent was missing a link to the deployment (which is available when you follow the link to the deploy log) --but that email was awesome, showing up after I created the PR!

Cheers!

[adriatic]

I think it needs a Search Box, but I’m not sure how to make that work in what seems like a markup site? (apologies if I’m missing something basic here)

This site exists as separate and parallel to the official docs site only until it gets merged into the official one. At. that time it will be “covered” by the exiting Algolia search

It’s very cool that PRs result in Preview deployment – that’s excellent! Do those get torn down automatically when the PR is closed? The email it sent was missing a link to the deployment (which is available when you follow the link to the deploy log) --but that email was awesome, showing up after I created the PR!

Credits for that belong to GitHub (unless I misunderstood you )

Status on 04/19/2022

The docs website reached the “first complete draft” status. The how to section is the exception to this status - being the key part of the docs website will be the area of focus now.

Any comments - please add to this thread or to this list of issues.

[adriatic]

Status on 04/22/2022

Reshuffle the site presented above, by removing the tools section, which was voted out by a “popular vote”. the how to section now contains two folders - how to test and how to debug as shown below

Each of these folders have many chapters each specific to a tool used in the related context:

At this point, the existing infrastructure is sufficiently evolved to start writing the information about Testing and Debugging Redwood applications.

Status on 04/25/2022

The above update (from 4/22) turned to be too optimistic - the sentence

At this point, the existing infrastructure is sufficiently evolved to start writing the information about Testing and Debugging Redwood applications.

needs to be corrected - it will take me a few more days to implement one complete tutorial for testing and one for debugging, to reach the point where I could put myself in a wait-state, hoping that some of the folks that expressed interest in helping could step based in the full understanding of what is expected to be done.

Here is the summary of the tandem project using a new vocabulary that will hopefully make it a lot more clear.

Tandem is a programmable set of Redwood specific tutorials explaining the techniques of testing and debugging on a real-life example application. This application ought to be well known to all RedwoodJS fans: it is the finished application that is the subject of teaching new RW folks how to write a RW app Redwood blog.

This application is available here as a clone of the original, maintained in RedwoodJS own repositories. Each specific sample, which is used in various tutorials site (as the source code of the application “spiked” with intentional bugs) is persisted as one of the many branches to be created in the tandem tutorial samples repository.

By saying that Tandem is a programmable set of Redwood specific tutorials, I imply that

all source code snippets like

const add = (a, b) => {
  return a + b
}

if (add(1, 1) === 2) {
  console.log('pass')
} else {
  console.error('fail')
}

are replaced with a repository that has many branches (see two paragraphs back) each containing a specific application in source code form, used in the given tutorial - offering complete flexibility to add more information without having to change the tutorial texts

and

the tutorial texts are easily replaced or added to the docusaurus based application skeleton at https://rw-community.org/. At the moment one can look at that app to examine the initial set of testing and debugging tutorials.

[adriatic]

Missing work to get the test/debug (tandem) app ready

I mistakenly concluded that the finished tutorial app repository has the code that matches the really finished app (the code created by the person running the tutorial, reaching the afterword stage of tutorial document).

I am now working on running the tutorial from the intermission stage all the way to the end - the afterword stage. Then the then current source code will be contained in tandem tutorial samples repository.

That code will be used as the start of the tandem tutorial.

[adriatic]

Status on 04/30/2022

Finished the very first tutorial article, from start to end (meaning that at this point, I could invite interested contribute to create theirs):

Before I continue with this in the style indicated by this first article, I will ask anyone with interest to help this project to state so in the reply to this (hopefully last) status report. Above all, I need feedback on all aspects, primarily on the clarity of this first tutorial.

[dom]

It looks like the updated link is supposed to be devtools setup | Testing and Debugging. Having a look now!

[dom]

I like where the article’s going. It’s the setup article, and I do feel setup at the end of it. We’ve yet to debug anything, so looking forward to trace (is it?) where we’ll use the chrome devtools to get to the bottom of a bug.

While this is pretty advanced, I think this video may help guide the content. I knew that chrome devtools were powerful, but didn’t know exactly how:

Debugging case study: broken stringifier

The author has several other debugging videos on his channel.

[adriatic]

Mateusz Burzynski videos seem great (did not yet go through them in a detailed fashion) and I contacted him to ask whether he would be a collaborator on this tandem project. Thanks @dom - great catch

[adriatic]

It looks like the updated link is supposed to be devtools setup | Testing and Debugging.

The observation you made is a feature of docusaurus - where only leaf nodes can be “clicked on”. Note that Redwood online documentation behaves the same:

The node “How To” is a folder (not a markdown document), so when you click on it that folder toggles from closed to opened (yellow marker 1). The node marked with 2 is leaf node (markdown document), se click on that node results in displaying its content.

---

It’s the setup article, and I do feel setup at the end of it. We’ve yet to debug anything, so looking forward to trace (is it?) where we’ll use the chrome devtools to get to the bottom of a bug.

You are correct - the devtools setup is the article describing the chrome devtools setup and I made it as a separate markdown file, so I can refer to it from other articles as well. I will also refer to other chrome developer tool article - like Console overview or JavaScript debugging reference but I plan to make such reference from a context of debugging RedwoodJS application.

---

We’ve yet to debug anything, so looking forward to trace (is it?) where we’ll use the chrome devtools to get to the bottom of a bug.

Correct again . As you likely remember from following my writings here, the application we will use as a debugging / testing “object” is the Redwood Blog many variants of which will be maintained in various branches of this repo (note that at the moment, it contains only the clone of

[adriatic]

@adriatic

Status on 05/05/2022

The tandem app reached the stage where it needs feedback from the developers. I has two tutorial sections: testing and debugging.

Each section offers several tools used in these disciplines. So, please define your preferences to help define the order of writing these markdown articles.

---