Acceptance Test POC and Setup

.gitignore

@@ -1,5 +1,10 @@
 .DS_Store
+.env.local
 *.log
 node_modules
 aws-exports.js
 aws-exports.ts
+
+# testing
+acceptance-tests/cypress/screenshots
+acceptance-tests/cypress/videos

CONTRIBUTING.md

@@ -0,0 +1,81 @@
+# Contributing
+
+## Getting Started
+
+1. Fork & Clone this repo
+1. [`nvm install`](https://github.com/nvm-sh/nvm)
+1. [`nvm use`](https://github.com/nvm-sh/nvm)
+1. `yarn install`
+
+## Documentation Development
+
+1. Run the documentation via `yarn docs`
+1. Visit <http://localhost:3000/>
+1. Create/Update content based on the URL.
+
+   For example, the content for
+   http://localhost:3000/components/authenticator is located at [`docs/src/content/components/authenticator/index.mdx`](docs/src/content/components/authenticator/index.mdx)
+
+Internally, this content is served by a single, Next.js [optional catch all route](https://nextjs.org/docs/routing/dynamic-routes#optional-catch-all-routes):
+[`docs/src/pages/[[...slugs]].tsx`](docs/src/pages/[[...slugs]].tsx).
+
+## React Development
+
+1. `yarn docs` to run the development server
+1. Create or Update an example at [`docs/src/pages/component/authenticator/examples/...`](docs/src/pages/component/authenticator/examples)
+
+   ```js
+   // .../authenticator/examples/sign-in.ts
+   import { Authenticator } from "aws-amplify-react";
+   import { Amplify } from "aws-amplify";
+   import "@aws-amplify/ui/dist/style.css";
+
+   // **You will need to provide this file yourself**
+   import awsExports from "./aws-exports";
+
+   Amplify.configure(awsExports);
+
+   export default function Example() {
+     return <Authenticator />;
+   }
+   ```
+
+1. Visit your example (.e.g. <http://localhost:3000/docs/src/pages/component/authenticator/examples/sign-in>)
+1. Make changes to [`@aws-amplify/ui-react`](packages/react) & save.
+
+   Next.js should automatically hot-reload your changes in the example.
+
+### Documentation & Testing
+
+1. Create or Update a `${feature}.feature` file (using [Gherkin](https://cucumber.io/docs/gherkin/reference/)) describing the behavior in [`packages/e2e/cypress/tests/acceptance/${slug}`](packages/e2e/cypress/tests/acceptance).
+
+   ```gherkin
+   Feature: My new feature
+
+     Documentation-friendly description of this feature, why it exists, & how to use it.
+
+     Scenario: Example scenario using this feature
+       Given some "STARTING_POINT"
+       When I DO "SOMETHING"
+       And I DO SOMETHING "ELSE"
+       Then I see "THE DESIRED BEHAVIOR"
+   ```
+
+1. Create or Update the accompanying `${slug}.feature` tests (e.g. `packages/e2e/cypress/tests/acceptance/${slug}/${feature}/${feature}.ts`
+1. Run `yarn workspace e2e dev` to load Cypress
+1. Click on your updated `${feature}.feature` file to validate your changes
+
+#### Vue Development
+
+1. `yarn dev:vue`
+1. Visit <http://localhost:3001/>
+
+#### Angular Development
+
+1. `yarn build:angular`, or `yarn build:angular:watch` for live development
+1. `yarn dev:angular`.
+1. Visit <http://localhost:4200/>
+
+#### Flutter Development
+
+1. see [packages/flutter/README.md](packages/flutter/README.md)

README.md

@@ -20,32 +20,5 @@
 ## Documentation
 
 The latest documentation is found here:
-> https://docs.amplify.aws/ui
-
-## Contributing
-
-### Getting Started
-
-1. Fork & Clone this repo
-1. [`nvm use`](https://github.com/nvm-sh/nvm)
-1. `yarn install`
-
-#### React Development
-
-1. `yarn dev`
-1. Visit <http://localhost:3000/>
 
-#### Vue Development
-
-1. `yarn dev:vue`
-1. Visit <http://localhost:3001/>
-
-#### Angular Development
-
-1. `yarn build:angular`, or `yarn build:angular:watch` for live development
-1. `yarn dev:angular`.
-1. Visit <http://localhost:4200/>
-
-#### Flutter Development
-
-1. see [packages/flutter/README.md](packages/flutter/README.md)
+> https://docs.amplify.aws/ui

angular-docs/package.json

@@ -21,7 +21,7 @@
     "@angular/platform-browser": "~11.2.5",
     "@angular/platform-browser-dynamic": "~11.2.5",
     "@angular/router": "~11.2.5",
-    "aws-amplify": "^3.3.25",
+    "aws-amplify": "latest",
     "ngx-markdown": "^11.1.2",
     "rxjs": "~6.6.0",
     "tslib": "^2.0.0",

docs/.gitignore

@@ -32,3 +32,23 @@ yarn-error.log*
 
 # vercel
 .vercel
+
+#amplify
+amplify/\#current-cloud-backend
+amplify/.config/local-*
+amplify/logs
+amplify/mock-data
+amplify/backend/amplify-meta.json
+amplify/backend/awscloudformation
+amplify/backend/.temp
+build/
+dist/
+node_modules/
+aws-exports.js
+awsconfiguration.json
+amplifyconfiguration.json
+amplifyconfiguration.dart
+amplify-build-config.json
+amplify-gradle-config.json
+amplifytools.xcconfig
+.secret-*

docs/package.json

@@ -8,13 +8,17 @@
     "start": "next start"
   },
   "dependencies": {
+    "@aws-amplify/ui-react-v1": "npm:@aws-amplify/ui-react",
+    "@cucumber/gherkin": "^19.0.3",
+    "@cucumber/messages": "^16.0.1",
     "@headlessui/react": "^1.2.0",
     "@heroicons/react": "^1.0.1",
     "@mdx-js/loader": "^1.5.1",
     "@mdx-js/react": "^1.6.18",
     "@moxy/next-compile-node-modules": "^2.0.2",
     "@next/mdx": "^9.1.1",
     "aws-amplify": "latest",
+    "aws-amplify-react": "latest",
     "gray-matter": "^4.0.3",
     "mdx-prism": "^0.3.3",
     "next": "latest",

docs/src/components/FeatureTests.tsx

@@ -0,0 +1,27 @@
+export function FeatureTests({ featureTests = [] }) {
+  if (!featureTests.length) {
+    return null;
+  }
+
+  return (
+    <>
+      <h2>Features</h2>
+
+      {featureTests.map(({ feature }) => (
+        <section key={feature.name}>
+          <h3>{feature.name}</h3>
+          <p>{feature.description}</p>
+
+          <h4>Examples</h4>
+          <ul>
+            {feature.children.map(({ scenario }) => (
+              <li key={scenario.name}>
+                <a href="#">{scenario.name}</a>
+              </li>
+            ))}
+          </ul>
+        </section>
+      ))}
+    </>
+  );
+}

docs/src/content/components/authenticator/index.mdx

@@ -29,6 +29,8 @@ function App() {
 export default withAuthenticator(App)
 ```
 
+<FeatureTests featureTests={featureTests} />
+
 ## Authenticator with Default Theme
 
 Amplify UI provides simple, clean styles to get started with a great experience in two steps:

docs/src/pages/[[...slugs]].tsx

@@ -1,14 +1,18 @@
 import { customComponents } from "@/components/customComponents";
 import { Layout } from "@/components/Layout";
 import { getContentPaths } from "@/utils/getContentPaths";
+import { getFeatureTestsFromSlug } from "@/utils/getFeatureTestsFromSlug";
 import { getPageFromSlug } from "@/utils/getPageFromSlug";
 import { theme } from "@aws-amplify/ui-react";
 import mdxPrism from "mdx-prism";
 import { GetStaticPaths, GetStaticProps } from "next";
 import { MDXRemote } from "next-mdx-remote";
 import { serialize } from "next-mdx-remote/serialize";
+import { FeatureTests } from "@/components/FeatureTests";
+import * as components from "@aws-amplify/ui-react";
 
 export default function Content({
+  featureTests = [],
   frontmatter,
   mdxSource,
   componentPages,
@@ -23,7 +27,12 @@ export default function Content({
     >
       <MDXRemote
         {...mdxSource}
+        components={{
+          ...components,
+          FeatureTests,
+        }}
         scope={{
+          featureTests,
           theme,
           customComponents,
         }}
@@ -54,7 +63,7 @@ export const getStaticProps: GetStaticProps = async ({ params }) => {
   });
 
   const { content, frontmatter } = await getPageFromSlug(slug);
-
+  const featureTests = await getFeatureTestsFromSlug(slug);
   const componentPagePaths = await getContentPaths("components/*/index.mdx");
   const componentPages = await Promise.all(
     componentPagePaths.map(getPageFromSlug).map(page => page.then(pluckMeta))
@@ -86,6 +95,7 @@ export const getStaticProps: GetStaticProps = async ({ params }) => {
     props: {
       frontmatter,
       componentPages,
+      featureTests,
       mdxSource,
       primitivePages,
     },

docs/src/pages/components/authenticator/examples/sign-in.tsx

@@ -0,0 +1,10 @@
+import { Authenticator } from "aws-amplify-react";
+import { Amplify } from "aws-amplify";
+import "@aws-amplify/ui/dist/style.css";
+import awsExports from "./aws-exports";
+
+Amplify.configure(awsExports);
+
+export default function Example() {
+  return <Authenticator />;
+}

docs/src/utils/getFeatureTestsFromSlug.tsx

@@ -0,0 +1,36 @@
+import {
+  AstBuilder,
+  GherkinClassicTokenMatcher,
+  Parser,
+} from "@cucumber/gherkin";
+import { IdGenerator } from "@cucumber/messages";
+import { readFile } from "fs/promises";
+import glob from "glob";
+import path from "path";
+
+const parser = new Parser(
+  new AstBuilder(IdGenerator.uuid()),
+  new GherkinClassicTokenMatcher() // or GherkinInMarkdownTokenMatcher()
+);
+
+export async function getFeatureTestsFromSlug(slug: string) {
+  const cwd = path.join(
+    process.cwd(),
+    "../packages/e2e/cypress/tests/acceptance",
+    slug
+  );
+
+  const featurePaths = glob.sync("**.feature", { cwd });
+  const featureFiles = await Promise.all(
+    featurePaths.map(featurePath =>
+      readFile(path.resolve(cwd, featurePath), "utf-8")
+    )
+  );
+
+  const featureTests = featureFiles.map(featureFile =>
+    parser.parse(featureFile)
+  );
+
+  // Strip `undefined` properties because they're not JSON-serializable by Next.js
+  return JSON.parse(JSON.stringify(featureTests));
+}

packages/angular/package.json

@@ -18,7 +18,7 @@
     "@angular/platform-browser": "~11.2.4",
     "@angular/platform-browser-dynamic": "~11.2.4",
     "@angular/router": "~11.2.4",
-    "aws-amplify": "^3.3.25",
+    "aws-amplify": "latest",
     "rxjs": "~6.6.0",
     "tslib": "^2.0.0",
     "zone.js": "~0.11.3"

packages/e2e/.gitignore

@@ -0,0 +1,6 @@
+# testing
+cypress/screenshots
+cypress/videos
+
+# environment
+.env

packages/e2e/cypress.json

@@ -0,0 +1,5 @@
+{
+  "baseUrl": "http://localhost:3000/",
+  "testFiles": ["**/*.{feature,features}"],
+  "integrationFolder": "cypress/tests"
+}

packages/e2e/cypress/fixtures/example.json

@@ -0,0 +1,5 @@
+{
+  "name": "Using fixtures to represent data",
+  "email": "hello@cypress.io",
+  "body": "Fixtures are a great way to mock data for responses to routes"
+}

packages/e2e/cypress/plugins/index.js

@@ -0,0 +1,31 @@
+/// <reference types="cypress" />
+// ***********************************************************
+// You can change the location of this file or turn off loading
+// the plugins file with the 'pluginsFile' configuration option.
+//
+// You can read more here:
+// https://on.cypress.io/plugins-guide
+// ***********************************************************
+
+const cucumber = require("cypress-cucumber-preprocessor").default;
+const resolve = require("resolve");
+require("dotenv").config();
+
+// This function is called when a project is opened or re-opened (e.g. due to
+// the project's config changing)
+
+/**
+ * @type {Cypress.PluginConfig}
+ */
+module.exports = (on, config) => {
+  const options = {
+    typescript: resolve.sync("typescript", { baseDir: config.projectRoot }),
+  };
+  // `on` is used to hook into various events Cypress emits
+  // `config` is the resolved Cypress config
+  on("file:preprocessor", cucumber(options));
+
+  // Assign .env variables to Cypress config
+  Object.assign(config.env, process.env);
+  return config;
+};

packages/e2e/cypress/support/commands.js

@@ -0,0 +1,22 @@
+// ***********************************************
+// For more comprehensive examples of custom
+// commands please read more here:
+// https://on.cypress.io/custom-commands
+// ***********************************************
+//
+//
+// -- This is a parent command --
+// Cypress.Commands.add('login', (email, password) => { ... })
+//
+//
+// -- This is a child command --
+// Cypress.Commands.add('drag', { prevSubject: 'element'}, (subject, options) => { ... })
+//
+//
+// -- This is a dual command --
+// Cypress.Commands.add('dismiss', { prevSubject: 'optional'}, (subject, options) => { ... })
+//
+//
+// -- This will overwrite an existing command --
+// Cypress.Commands.overwrite('visit', (originalFn, url, options) => { ... })
+import "@testing-library/cypress/add-commands";