bigtestjs/bigtestjs.io

All BigTest development has moved to https://github.com/thefrontside/bigtest

⚠️ DEPRECATED ⚠️

In order to make BigTest development faster and friction free, we've consolidated all of our individual projects into a single repository on the Frontside Organization. We'd love to see you there!

https://bigtestjs.io

This is the source code for the all new BigTest website

Prerequisites

1. Ruby
2. Bundler
3. Node

Installation

1. bundle install
2. yarn install

Run Locally

Use middleman to fire up a local server at http://localhost:4567

Deploying

The website is deployed to Heroku once CI passes on master. To implement your changes, open an pull request. Once merged with master, your changes will be visible in a few minutes.

bigtestjs.io's Issues

Create landing page for quick start link (and quest issue for quick start)

We need to link to a page that links to the quest issue (that still needs to be made) so we can detail everything that needs to be done to make a quick start guide happen.

The goal is to pack the quest issue full of details so anyone can help contribute if they wish

Figure out how to get builds to come from bigtest-bot

Currently review app & master deploys are coming from my account. It'd be dope to have those come from bigtest-bot.

I think we're going to have to create a bigtest-bot user account for heroku & then resetup the pipeline with that account.

Function argument defaults are not displayed

For example, this documentation specifies a default value, but the website does not currently display this information

/**
 * @param {String} [arg="default value"] - An optional argument with a default value
 */

Add contributing.md

We should add a contributing.md file detailing how to get the project setup, how to run tests, & possibly explain how the tests work.

(moved from thefrontside/bigtest#79)

Google Analytics

It would be really nice to understand how our website is being used.

Guide for working with React

• setting up the test harness
• loading data
• interacting
• highlights pure assertions (and async / await as an alt)

(moved from thefrontside/bigtest#39)

Typescript support?

Does Bigtest have support for Typescript? If so, are there any additional setup steps I need to take to import ts and tsx files?

Set up cache busting for assets

When the site is deployed with changes, it can take a while for the browser cache to clear itself. Sometimes it even takes a hard refresh to get any new styles.

This should be as simple as adding activate :asset_hash to our middleman config during production builds. Documentation

Update @bigtest/interactor docs

The @bigtest/interactor docs need work. The documentation is there, but the tags are incomplete, causing the pages to render with weird and missing content.

Follow up from #6

Update title of page when on docs

Currently when you're on a specific docs page (interactor for example) the title doesn't reflect that. It just says "BigTest". The title could be a little more helpful here.

Update README url

I renamed the repo since we're no longer using .js.org to reflect our domain name. We should update the README to reflect that change

Create a guides index page

Purpose

Create an index page for the guides page. This issue will also probably setup the layout for the page. I imagine we'll have a layout similar to the docs pages (with a sidebar).

This issue is pretty open. Whatever you feel is the most helpful for a guides index. I'd start off doing research on what makes a good index.

Specify Interactor default scope in introduction

I've noticed when others are using interactors, they tend to leave out the scope selector and instead of using defaultScope, they specify the root selector in every property.

This sometimes makes it impossible for those interactors to be reusable. Since people don't know that the scope defaults to document.body, there are instances where attempting to reuse those interactors results in only the first instance of those elements ever being interacted with.

Right after the introduction example, we should specify what happens when you do not specify a selector. And in the custom interactors guide, we should strongly suggest to not specify the root selector for every property. For example: "if you find yourself repeating the same selector in your properties, try composing an interactor scoped specifically to that selector instead."

Adjust scroll position when clicking doc sidebar

When you click a doc in the sidebar it's going to scroll to that doc on the page. Most of the time the title of the doc is covered up by the sticky header which makes it so I have to scroll up a bit to make sure it's the right doc.

Here's a gif example of it:

Add issue / PR template

I'm not sure if we have a standardized template. Maybe we can adapt something from x-select? https://github.com/thefrontside/emberx-select/blob/master/.github/ISSUE_TEMPLATE.md

(moved from thefrontside/bigtest#78)

Explain the philosophy behind BigTest

It would be helpful for new comers to understand what is driving us to build this, where we came from, and what we're looking to achieve with BigTest.

Add service worker to cache docs & go offline first

It would be really cool for us to cache the BigTest docs offline first so you don't have to have network connection to view our documentation.

This ticket should be implemented after #28. We must set up cache busting so users don't permanently get stuck with an old version of the docs site.

This is a pretty good resource I found for implementing a service worker for offline first if you haven't done it before: https://css-tricks.com/serviceworker-for-offline/

Create introduction guide

Purpose

Create an introduction guide for BigTest explaining the following:

• Why BigTest? / What does BigTest do different?
• Testing philosophy
• Convergence
• Speed benefits
• Interactor
• CLI
• Mirage
• Comparison to competitors
• How to select from the DOM (ex: data-test-app-my-select)

Create glossary

We should create glossary for all the terms we throw around so people can have a shared understanding of what we're saying.

• test runner
• interactor
• convergence
• test harness
• server mock
• etc

This list should be comprehensive

Homepage CTA paragraphs

The homepage call to action paragraphs need icons & links (an actual CTA) to their respective guides for each section. This is what it currently looks like:

Add google analytics

As the title says, add google analytics to track traffic

Create better API docs index

We could use this index as a place to explain the process behind how the docs are generated.

Force SSL

We should force all traffic to https.

Guide for a golden path tutorial

A general introduction to BigTest, what's different, what makes it special, and understanding the key concepts. 🔑

Docs sidebar sticky on scroll

When scrolling through the list of docs it would be nice for the sidebar where all of the methods, functions, and properties live to scroll with you.

Currently:

What the fix could look like:

Create link to "edit this page on github"

Purpose

I love when docs sites make it really easy for me to edit their docs. For our guides at least we should offer this functionality.

The docs for the packages will probably be a little tricker so that can be a follow up issue if that's the case.

Approach

I'd probably create a helper that links to that page in the source (https://github.com/bigtestjs/bigtestjs.io/blob/master/source/${my-path-here}).

A nice benefit of middleman is the path you see in the browser is will match the url above because the structure of inside of the source folder is the structure of the URL.

Link to the chatroom on the website

Why not invite people to chat about BigTest right from the BigTest website.

Redirect bigtestjs.com to bigtestjs.io

This is something one of us in FS need to do.

Blog / Media Page

We need somewhere to link out to things written about BigTest. Until that is built, let's put links here to existing content.

• https://frontside.io/blog/2018/06/13/big-testing-in-react/
• https://medium.com/@robdel12/jest-bigtest-interactor-component-test-%EF%B8%8F-11b1947954c8

Create a quick start guide

Purpose

Create a quick start guide for BigTest. If you would like to help with this issue I'm available to explain anything you might have questions with!

A possible outline for the quick start guide could be:

• Briefly explain the benefits of BigTest
• Give a TL;DR maybe?
  • Render your app into a browser with karma, drive the app around on the page with interactor, and assert change with mocha/chai
• Explain what a convergence is
• Explain what an interactor is
• Create an outline of tasks being covered in the quick start (a little overview)
• Go over configuring the test setup with:
  • Karma
    • Mention the tests/index.js fix. (We create an index file that creates a single bundle of all test files to avoid duplicate react instances inside the react test container)
  • Webpack
    • Possibly mention what karma-webpack is doing
    • Mention something about issue for integrating with other build tools
  • React
    • Building the application test harness
  • @bigtest/mirage
    • how to mock a single end point
    • create a factory for the end point
  • @bigtest/mocha
    • chai
• Writing your first test
• Integrating with your apps router
  • Offer integration with React Router
• Write test that navigates
• Write a test that mocks data with mirage
• Wrap up

We should provide an example application which we wrap tests around.

Display possible errors thrown by functions

The API docs display arguments and return values, but lack possible errors documented like this:

/**
 * @throws {Error} when something goes wrong
 */

Remove `@bigtest/convergence` meta info

The @bigtest/convergence include some meta info. We should either ignore this info in the templates, or just remove it in the docs generation script.

Follow up from #6

(p.s. I struggled with the label. Is it a bug or a feature?)