From 8771481890249f28cab2c626ff989712e7f42436 Mon Sep 17 00:00:00 2001
From: Adam Mcgrath <adam.mcgrath@auth0.com>
Date: Wed, 17 Jun 2020 16:02:12 +0100
Subject: [PATCH] [SDK-1704] Add contributing and troubleshooting guides (#39)

* Add contribution guide

* Add troubleshooting guide

* Fix a flakey test caused by Next.js hydrating the DOM
---
 CONTRIBUTING.md                   | 40 +++++++++++++++++++++++++++++++
 README.md                         |  6 +++++
 TROUBLESHOOTING.md                | 10 ++++++++
 cypress/integration/smoke.test.ts |  2 +-
 4 files changed, 57 insertions(+), 1 deletion(-)
 create mode 100644 CONTRIBUTING.md
 create mode 100644 TROUBLESHOOTING.md

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 00000000..3040418e
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,40 @@
+# Contributing
+
+We appreciate feedback and contribution to this repo! Before you get started, please see [Auth0's general contribution guidelines](https://github.com/auth0/open-source-template/blob/master/GENERAL-CONTRIBUTING.md)
+
+## Local development
+
+Install the dependencies and start the development server:
+
+```bash
+npm install
+npm start
+```
+
+This will run a development server at http://localhost:3000 with a simple application that demonstrates the main features of the SDK. When you make changes the development server will live reload.
+
+You can change the default Auth0 tenant and application by editing the domain and clientId in [static/index.html](./static/index.html#L81-L82)
+
+## Running the examples
+
+The examples are React applications and an Express API. To run the example apps see the instructions in [examples/README.md](./examples/README.md)
+
+## Running the unit tests
+
+The unit tests use Jest and are run with:
+
+```bash
+npm test
+```
+
+## Running the integration tests
+
+The integration tests run against the examples, so you must follow the instructions to set up the examples in [examples/README.md](./examples/README.md) first.
+
+Then run:
+
+```bash
+CYPRESS_USER_EMAIL={YOUR USER} CYPRESS_USER_PASSWORD={YOUR PW} npm run test:integration
+```
+
+`CYPRESS_USER_EMAIL` and `CYPRESS_USER_PASSWORD` should be the credentials of a user on your Auth0 tenant that has the `read:users` permissions on the audience you specified when setting up the examples.
diff --git a/README.md b/README.md
index efcd6259..79b2e406 100644
--- a/README.md
+++ b/README.md
@@ -18,6 +18,7 @@ Auth0 SDK for React Single Page Applications (SPA).
 - [Getting Started](#getting-started)
 - [Contributing](#contributing)
 - [Support + Feedback](#support--feedback)
+- [Troubleshooting](#troubleshooting)
 - [Vulnerability Reporting](#vulnerability-reporting)
 - [What is Auth0](#what-is-auth0)
 - [License](#license)
@@ -193,11 +194,16 @@ We appreciate feedback and contribution to this repo! Before you get started, pl
 
 - [Auth0's general contribution guidelines](https://github.com/auth0/open-source-template/blob/master/GENERAL-CONTRIBUTING.md)
 - [Auth0's code of conduct guidelines](https://github.com/auth0/open-source-template/blob/master/CODE-OF-CONDUCT.md)
+- [This repo's contribution guide](./CONTRIBUTING.md)
 
 ## Support + Feedback
 
 For support or to provide feedback, please [raise an issue on our issue tracker](https://github.com/auth0/auth0-react/issues).
 
+## Troubleshooting
+
+For information on how to solve common problems, check out the [Troubleshooting](./TROUBLESHOOTING.md) guide
+
 ## Vulnerability Reporting
 
 Please do not report security vulnerabilities on the public GitHub issue tracker. The [Responsible Disclosure Program](https://auth0.com/whitehat) details the procedure for disclosing security issues.
diff --git a/TROUBLESHOOTING.md b/TROUBLESHOOTING.md
new file mode 100644
index 00000000..24815dd2
--- /dev/null
+++ b/TROUBLESHOOTING.md
@@ -0,0 +1,10 @@
+# Troubleshooting
+
+When your application is not behaving as expected:
+
+- Check for any messages in the console
+- Check the Network Activity especially any requests to your authorization server
+- Check the log data in your [Auth0 Dashboard](https://manage.auth0.com#/logs)
+- Check the `@auth0/auth0-spa-js` [FAQs](https://github.com/auth0/auth0-spa-js/blob/master/FAQ.md)
+
+If you believe there is a bug in the SDK, [raise an issue](https://github.com/auth0/auth0-spa-js/issues/new/choose). Be sure to include all the information required to reproduce the issue.
diff --git a/cypress/integration/smoke.test.ts b/cypress/integration/smoke.test.ts
index f8356f1c..af33172f 100644
--- a/cypress/integration/smoke.test.ts
+++ b/cypress/integration/smoke.test.ts
@@ -17,7 +17,7 @@ describe('Smoke tests', () => {
   it('do basic login and show user', () => {
     cy.visit('/');
     cy.get('#login').should('exist');
-    cy.get('#login').click();
+    cy.get('#login').click({ force: true });
 
     loginToAuth0();