Create documentation site for beta release

[cowboyd]

These pieces of documentation were the ones identified as being critical to get folks on-boarded into the bigtest eco-system:

• Getting started
  • Installation
    • adding bigtest to your project
    • setting up browsers for testing (including webdriver caveats)
  • Development Workflow
  • Setting up CI
    • GitHub Actions
    • CircleCI
  • Code Coverage Add code coverage guide #569
• Concepts
  • Test tree
  • Steps vs Assertions
  • Interactors
    • what is a locator, and how do I think about it?
    • ensure weird mutable apis like NodeList cannot be used in filters
• Example App
• Stubbing API

Some documentation sites we could do worse than emulating:

• https://redux.js.org/
• https://mswjs.io/docs/

[jorgelainfiesta]

I think we should also have a page on declarative tests, and not mention yet that there's a procedural way. We can add that later on under an 'advanced' section.

[cowboyd]

@jorgelainfiesta when you say declarative tests, are you talking about writing objects with descriptions and actions? vs bare async functions?

[jorgelainfiesta]

@cowboyd yeah exactly

[minkimcello]

So while typing out the first draft for Getting Started, I did some reorganizing of how we could structure the rest of the docs.

• Getting Started
  • Installation
  • Writing Your First Test
• Guides
  • Interactors - (❗ This was under Concepts but I think should come immediately after Getting Started because I imagine people will be wondering "what are interactors" right after following along with the Write Your First Test section).
    • What are interactors
    • Built-in interactors
    • Locators and Filters
      • ensure weird mutable apis like NodeList cannot be used in filters
  • Development Workflow
    • bigtest server vs bigtest test vs bigtest ci
    • Setting up CI
      • Github Actions
      • CircleCI
  • Configure Browsers
    • webdriver caveats
    • multi-browser parallel testing
  • iOS and Android Simulators
  • Setup Code Coverage
• Concepts
  • Test Tree
  • Steps and Assertions
    • Grouping syntax
    • Describe how steps always run before assertions
    • Declarative tests as @jorgelainfiesta mentioned. This section can be linked to earlier in the guides so when people are reading about interactors and thinking "okay, how do I write assertions or steps without interactors?"
• API - auto-generated from code using tsdocs, typedoc or gatsby-source-typedoc
• Stubbing API - (❓ maybe we should create Advanced category and put this there or under Concept?)

Thoughts?

[cowboyd]

@minkimcello These suggestions make a lot of sense. If we can get some confirmation from @jorgelainfiesta, let's go ahead and update the outline in the issue.

[jorgelainfiesta]

@minkimcello great! Moving the Interactors up is definitely a good one.

During the demo with TestDouble, they mentioned that the way of writing tests in BigTest was difficult because it was not as one could be used to. Should we have a section on writing tests in the top part, where we introduce like some basic use-cases?

Could be the equivalent of https://docs.cypress.io/guides/core-concepts/writing-and-organizing-tests.html

Development Workflow - (❓ would interactive CLI go here?)

Charles has mentioned that most of the work on BigTest is done through the CLI, so that would make sense. The errors are still a bit unclear to me, perhaps we can talk about the errors you can get as well? Perhaps a comment on how to debug would be useful too.

Setting up CI - (❓ is there anything special here that needs to be mentioned aside from having to configure browser to be headless?)

I don't know the current state of affairs, but what do they need to effectively have virtual browsers running on CI? like do they need to pay a service to test against iOS Safari, for instance, or is it headless as well?

Stubbing API - (❓ maybe we should create Advanced category and put this there or under Concept?)

To my understanding, it's still unclear what we'll do here. I'd put it on hold, perhaps ratake it later on?

[minkimcello]

@jorgelainfiesta

During the demo with TestDouble, they mentioned that the way of writing tests in BigTest was difficult because it was not as one could be used to. Should we have a section on writing tests in the top part, where we introduce like some basic use-cases?

Huh? The Writing Your First Test is in the Getting Started section. Was there something in particular you wanted included?

I don't know the current state of affairs, but what do they need to effectively have virtual browsers running on CI? like do they need to pay a service to test against iOS Safari, for instance, or is it headless as well?

I haven't tried Safari yet but I'm working this section next so I'll start fiddling with it.

[minkimcello]

I thought creating a fake website with dropdown menus would take up unnecessary time (and we would probably end up redoing most of it anyway) so I just created a pull request and split up the doc drafts into markdown files and organized them into different directories. I hope this isn't the weirdest way of gathering material.

#661

[minkimcello]

Update: I'm currently working on organizing running-tests/ci-setup/browser-config.

Below are some of the things still on the agenda:

• styling @jorgelainfiesta
• api @jnicklas?
• docs
  • interactors - need help with introduction
  • code coverage
  • concepts
    • steps/assertions
    • test tree
• getting docs reviewed by editor

[minkimcello]

Can we close this and continue discussion over at #683?

[cowboyd]

@minkimcello yes indeed. Thanks for remembering