diff --git a/packages/docs/README.md b/packages/docs/README.md
index 00e387d8..1926e6f4 100644
--- a/packages/docs/README.md
+++ b/packages/docs/README.md
@@ -1,54 +1,47 @@
# Contoso Real Estate: Developer Guide
-> ๐ง **WORK IN PROGRESS:**
-_This package is currently under active development. Contributions will be welcomed once we release the first stable version_.
+> ๐ง **This is a Work in Progress:**
+_Once we commit a stable first version, this notice will be removed and package opened to contributions_.
-## About This Package
+## โน๏ธ | About This Package
-This is the "documentation" package for the Contoso Real Estate reference sample. It currently has 2 components:
+This is the "developer guide" documentation package for the Contoso Real Estate reference sample. It has 2 components:
- - **`website/`** | this is a _static website_ that provides a developer guide for self-guided exploration of the documentation from _design_ to _deployment_ steps. For more details, read the [website/README](website/README.md).
+ - **`website/`** | source for the _static website_ hosting a developer guide for self-guided exploration of documentation from _design_ to _deployment_ steps. See [website/README](website/README.md) for details.
- - **`training/`** | this point to _interactive workshops_ that help you explore the sample in a hands-on, step-by-step manner ex: _Learn Live_ events. For more details, read the [training/README](website/README.md).
+ - **`training/`** | content for _interactive workshops_ to explore sample in a hands-on, step-by-step manner ex: _Learn Live_ events. See [training/README](website/README.md).
-## About: Website
+## ๐ | Local Preview
-The source can be found under `website/` and a detailed description of the setup and configuration can be found in [`website/README.md`](website/README.md).
-
-1. The site features an interactive developer guide documenting the developer experience from defining the problem to deploying the solution. Think of it as static documentation.
-2. The site is built using [Docusaurus](https://docusaurus.io) with content authored in Markdown or MDX (JSX-flavored Markdown), allowing us to add interactive React components if needed (ex: Swagger-based API docs)
-3. The site has built-in support for [Playwright](https://playwright.dev) tests to validate that content is accessible, has no broken links and has a desired workflow (valid routes). _They are not part of the E2E testing strategy for the Contoso Real Estate application (those tests are in: `packages/testing`)_.
-
-**๐ | QUICKSTART**
-
-The recommended use of the website is by launching a local dev server for preview as shown below, either within Codespaces on in your local development environment.
+We recommend using the dev server to view the guide locally. This command will start the dev server _and_ launch browser to the correct preview URL.
```bash
# Requires Node.js v18+.
-# We recommend using nvm to install and manage versions
+# Recommend using nvm to manage versions
$ nvm use --lts
Now using node v18.17.0 (npm v9.6.7)
-# Switch to website folder and install dependencies
+# Install dependencies
$ cd website/
$ npm install
-# Run the dev server
-# Browser should launch automatically to the URL shown
+# Run dev server (should launch browser)
$ npx docusaurus start
[INFO] Starting the development server...
[SUCCESS] Docusaurus website is running at: http://localhost:3000/
-# ๐ Congratulations! You are previewing the dev guide.
-# Any changes made in website/* will be reflected instantly
-
+# ๐ Congratulations!
+# You should be previewing the dev guide on browser
```
-Docusaurus does provide [Deployment guidance](https://docusaurus.io/docs/deployment) if you want to deploy this to a static hosting service like Azure Static Web Apps or GitHub Pages. _If you go this route, we recommend you do this in a personal fork and setup GitHub Actions for automating build/deploy_. Here's how you build for production:
+## ๐ | Production Build
+
+You can build the website for production deployment and validate that build with a local preview as well:
```bash
-# Create a production-ready static build of website
+# Requires Node.js v18+
+# Build the static site for production
$ cd website/
$ npm install
$ npm run build
@@ -56,65 +49,50 @@ $ npm run build
[SUCCESS] Generated static files in "build".
[INFO] Use `npm run serve` command to test your build locally.
-# Preview the build version locally
-# If default port 3000 is in use, it will automatically pick another.
-# Browser will launch automatically to the URL shown
+# Preview the production build locally
+# Will attempt to run this on port 3000 (default)
$ npm run serve
+# You will be prompted if port is unavailable
+# Browser is automatically launched to the
+# preview server URL as shown.
[WARNING] Something is already running on port 3000. Probably:
Would you like to run the app on another port instead? โฆ yes
[SUCCESS] Serving "build" directory at: http://localhost:3001/
```
+The build can now be deployed to suitable hosting services. Check out the Docusaurus [Deployment](https://docusaurus.io/docs/deployment) documentation for service-specific guides. We verified this works with GitHub Pages and Azure Static Web Apps.
+Since this is an open-source repo focused on an engineering sample, we are not actively hosting the developer guide ourselves. However, we encourage you to explore deployment options in your personal fork - and use GitHub Actions to automate the build/deploy workflow for convenience.
+## ๐ญ | Playwright Testing
-
-## About the Website
-
-This is an interactive _developer guide_ for the Contoso Real Estate application. It provides more detailed documentation -- from application requirements and user scenarios to implentation services and developer experience -- for hands-on exploration of this open-source sample.
-
-Content is built using theplatform, a popular static site generation platform that supports content in both Markdown and MDX (JSX-flavored Markdown). To learn more about how this was setup, read [website/README.md](website/README.md).
-
-The website also has built-in that are **independent of** the test suite for the Contoso Real Estate app in `packages/testing` package. They are meant for validating website accessibility and functionality - and are not part of the end-to-end testing strategy for the reference sample itself. To learn more about the website testing focus and setup, read [website/README.TESTING.md](website/README.TESTING.md).
-
-### Preview The Website
-
-You need Node.js v18+. We recommend using `nvm` to manage your Node.js installs, and using the `lts` (long-term support) version where possible.
+[Playwright](https://playwright.dev) is a reliable end-to-end testing framework for modern web apps that supports test automation and cross-browser testing along with rich tooling to make the developer e2e testing experience seamless and productive.
```bash
-$ nvm use --lts
-Now using node v18.17.0 (npm v9.6.7)
-```
+# Get the Playwright version
+$ npx playwright --version
+Version 1.36.2
-Change to the `website/` folder and install dependencies.
+# Get usage help for available Playwright CLI commands and options
+$ npx playwright --help
+Usage: npx playwright [options] [command] ....
-```bash
-$ cd website
-$ npm install
-```
+# Get usage help for a specific Playwright CLI command (ex: test)
+$ npx playwright test --help
+Usage: npx playwright test [options] [test-filter...]
-Start the development server
-```bash
-$ npx docusaurus start
-[INFO] Starting the development server...
-[SUCCESS] Docusaurus website is running at: http://localhost:3000/
+run tests with Playwright Test
+...
```
-Docusaurus runs the preview server on port `3000` by default. If that is already in use, it will ask to use an alternative port seamlessly. In either case _it should launch the preview site inyour default browser automatically_.
-
-> ๐ | Congratulations!! Your website is running!
-
-
-### Deploy the Website
+The `package/docs` workspace now has a local set of Playwright tests for the _developer guide_ website. These are intentionally kept separate from the Playwrite e2e tests suite for the _Contoso Real Estate_ sample app located in the `package/testing` workspace.
-You can also choose to deploy the website to a static site hosting service **from your own fork**.
+As a result, there may be minor variations in how the two test runners are configured, and the kinds of test suites that are defined. To explore how the **website** tests are setup, configured, and run, go to [website/README.TESTING](./website/README.TESTING.md).
- - We verified this works with GitHub Pages and Azure Static Web Apps - and recommend using GitHub Actions for automated deploys with code changes.
- - Docusaurus also has [Deployment guidance](https://docusaurus.io/docs/deployment) for other hosting options if you have a preferred provider.
## Want to help?
Want to file a bug, contribute code or content, or improve the documentation and training resources? Excellent!
- Read up on our guidelines for [contributing](./CONTRIBUTING.md).
- Check out [open issues](https://github.com/Azure-Samples/contoso-real-estate/issues) that could use help.
- - File [a new issue]().
\ No newline at end of file
+ - File [a new issue](https://github.com/Azure-Samples/contoso-real-estate/issues/new/choose) to start a related discussion.
\ No newline at end of file
diff --git a/packages/docs/website/.env.example b/packages/docs/website/.env.example
new file mode 100644
index 00000000..aee6163c
--- /dev/null
+++ b/packages/docs/website/.env.example
@@ -0,0 +1,6 @@
+BASE_URL= # https://30daysof.github.io/contoso-real-estate/
+DEVSRV_URL= # http://localhost:3000
+TIMEOUT= # 30000
+TIMEOUT_EXPECT= # 5000
+PLAYWRIGHT_HTML_REPORT= #./static/playwright-report
+```
\ No newline at end of file
diff --git a/packages/docs/website/README.TESTING.md b/packages/docs/website/README.TESTING.md
index cf147379..b8b8d240 100644
--- a/packages/docs/website/README.TESTING.md
+++ b/packages/docs/website/README.TESTING.md
@@ -1,164 +1,159 @@
-## Website Testing with Playwright
+# Website Testing with Playwright
-This website is tested using [Playwright](https://playwright.dev/), a modern framework for reliable end-to-end testing and automation of modern web apps.
+## 1. Quickstart
+ ๐๐ฝ | Want the quickest start to testing? Try this!
-## 1. Playwright Setup
+Make sure that you don't have anything running already on port `3000` (default dev server port for Docusaurus) first before you follow the script below.
-Expand sections below for more details on initial setup.
+```bash
+# Change to website directory
+$ cd bash
- 1. Install Playwright
+# Make sure you have Node.js v18+ and install dependencies
+$ npm install
-To get started with Playwright, you can pick one of two options:
- - Use the [commandline](https://playwright.dev/docs/test-components#step-1-install-playwright-test-for-components-for-your-respective-framework)
- - Use the [VS Code extension](https://playwright.dev/docs/getting-started-vscode).
+# Run the Playwright test
+$ npm run tests
- We'll use the first option here for completeness, but will rely primarily on the second for all authoring, running, and debugging actions. Please [install the Playwright extension for VS Code](https://marketplace.visualstudio.com/items?itemName=ms-playwright.playwright) if you have not already done so.
+# View the Playwright generated HTML test report
+$ npm run report
+ Serving HTML report at http://localhost:9323. Press Ctrl+C to quit.
-Here's how we installed Playwright:
-```bash
-# Use valid Node.js environment
-$ nvm use --lts
-Now using node v18.17.0 (npm v9.6.7)
-
-# Check current Playwright stable release
-$ npx playwright --version
-Version 1.36.2
-
-# Initialize Playwright setup in website/
-# Use defaults for all questions asked during install
-$ cd packages/docs/website
-$ npm init playwright@latest
-Need to install the following packages:
- create-playwright@1.17.128
-Ok to proceed? (y)
-
-Getting started with writing end-to-end tests with Playwright:
-Initializing project in '.'
-โ Do you want to use TypeScript or JavaScript? ยท TypeScript
-โ Where to put your end-to-end tests? ยท tests
-โ Add a GitHub Actions workflow? (y/N) ยท false
-โ Install Playwright browsers (can be done manually via 'npx playwright install')? (Y/n) ยท true
-..
-..
-
-Happy hacking! ๐ญ
+๐ญ And you're done!!!
```
- 2. Explore Scaffold
+ ๐๐ฝ | Want to view the test results? Check the reports
+
+Before we look under the hood, let's take a quick look at what the report looks like and correlate it to what you will see in the [basic test specification](./tests/01-basic.spec.ts) used at this time.
+
+The landing page of the report gives you the summary:
+ - The number of tests run altogether (12) - with #passed, failed or skipped
+ - The numner of browsers tested on (3 color tags) - giving 4 tests per browser.
+ - The execution time for each test (likely different per browser, test case)
-_What did this do? Here are the main file changes:_
+![HTML Reporting Dashboard for Playwright](./static/docs/png/playwright-report-sample.png)
-1. Updated website/.gitignore to ignore the following if present
- - test-results/, playwright-report/, playwright/.cache
-2. Updated website/package.json and website/package-lock.json
- - Added @playwright/test dependencies and version ^1.36.2
-3. Added the playwright configuration file
- - See `playwright.config.ts`
-4. Added playwright test specification starter & demo files
- - Starter: `tests/example.spec.ts`
- - Demo: `tests-examples\demo-todo-app.spec.ts`
+Clicking on any test row takes you to these details:
+ - Time taken in setup ("Before") and teardown ("After") - by fixture!
+ - Time taken to execute test step - with code details for step
-We'll primarily focus on the configuration file and test specifications in the `tests/` folder.
- - Add `/tests-examples` to `website/.gitignore`. This lets us explore and use it for understanding initially, but not commit it to repo for long term.
- - Rename `example.spec.ts` to `website.spec.ts`. This is our core test spec.
+![Details on a single Playwright test](./static/docs/png/playwright-report-sample-details.png)
-Let's validate that Playwright was setup correctly. We can walk through the commands recommended in the setup output:
+ ๐๐ฝ | Want to view more detailed traces? Try this option!
+
+The Playwright test runner is configured to capture deeper traces only `on-first-retry`. This is because running traces adds non-trivial costs, even though it provides more fine grained trace data for debug.
+
+But what if you want to debug this on the fly? Override it using CLI options:
```bash
-# -- set current working directory as website/
-$ cd website/
-
-# Run end-to-end tests
-$ npx playwright test
-Running 6 tests using 6 workers
-...
-
-# Open last report
-$ npx playwright show-report
-Serving HTML report at http://localhost:9323. Press Ctrl+C to quit.
-
-# Starts the interactive UI mode.
-# This launches a Trace Viewer like window for live test results
-$ npx playwright test --ui
-
-# Runs the tests only on Desktop Chrome.
-$ npx playwright test --project=chromium
-Running 2 tests using 2 workers
-...
-
-# Runs the tests in a specific file.
-# File must be in the subtree of `testDir` folder specified in config
-# Ex: the command below looks for tests/*/website.spec.ts
-$ npx playwright test website
-Running 6 tests using 6 workers
-...
-
-# Runs the tests in debug mode.
-# This launches headless browser with a Playwright Inspector window beside it
-$ npx playwright test --debug
-Running 6 tests using 1 worker
-...
-```
+# Run the tests with trace on
+$ npx playwright test --trace on
-Note that running tests will create two directories that are .gitignored.
- - `test-results/` = contain artifacts generated by tests
- - `playwright-report/` = contains artifacts generated by html-reporter
+# Launch browser to show this report
+$ npx run report
+```
-Later, we'll switch to doing these actions using VS Code extensions. And we can configure the folder locations and other parameters via the CLI or config file.
+What does _this_ do to the generated reports? Now the details view gets a "Traces" section with richer visualizations. Also note how the time taken for tests is now significantly higher (see before/after steps). The data (zipfile) also adds storage requirements - both of which can add up quickly if run across all test cases and specifications, on a regular cadence (CI/CD).
- 1. Configure Test Runner
1. Author Test Specs
-
+First, let's install Playwright. There are two options available:
-Expand sections for brief introductions to developer tooling in Playwright.
+ - Use the [commandline (CLI)](https://playwright.dev/docs/test-components#step-1-install-playwright-test-for-components-for-your-respective-framework)
+ - Use the [VS Code extension](https://playwright.dev/docs/getting-started-vscode).
- 1. Playwright Extension
- 2. Playwright CLI
- 3. Playwright UI Mode
4. Test Authoring
+ ๐๐ฝ | Want to understand the structure of a test specification?
+
+๐ง TODO: Explain what `test spec` format is, why locators matter, what fixtures are, and why we may need to configure or observe timeouts.
+
5. Test Debugging
+ ๐๐ฝ | Want to understand test configuration settings & overrides?
+
+๐ง TODO: Explain what we are configuring, why we have `.env`, why we activated `webserver` and why we have timeouts in both test and webserver levels.
+
6. Test Reporting
+ ๐๐ฝ | Want a more interactive testing workflow? This is magical!
+
+๐ง TODO: Explain what `npm run test-ui` does in project
+
>>1,le=C[V];if(0
"},0:function(){return e.length&&Ph(e)},1:function(){return Rt(e,"b")},3:function(){return Rt(e,"i")},4:function(){return Rt(e,"u")},8:function(){return Go(e,"display:none")},9:function(){return Rt(e,"strike")},22:function(){return Go(e,"font-weight:normal;text-decoration:none;font-style:normal")},23:function(){return su(e,"i")},24:function(){return su(e,"u")},39:function(){return Qo(e,n.fg)},49:function(){return Ko(e,n.bg)},53:function(){return Go(e,"text-decoration:overline")}},o;return r[t]?o=r[t]():4