Skip to content

Commit

Permalink
Merge pull request #2 from Azure-Samples/main
Browse files Browse the repository at this point in the history 
docs: setup Playwright test harness for website (Azure-Samples#247)
  • Loading branch information
@nitya
nitya committed Aug 3, 2023
2 parents 2e93c4c + 535ca6a commit 52232ae
Show file tree
Hide file tree
Showing 48 changed files with 535 additions and 245 deletions.
104 changes: 41 additions & 63 deletions packages/docs/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,120 +1,98 @@
# 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:** <br/>
_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
...
[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]().
- File [a new issue](https://github.com/Azure-Samples/contoso-real-estate/issues/new/choose) to start a related discussion.
6 changes: 6 additions & 0 deletions packages/docs/website/.env.example
View file
Original file line number Diff line number Diff line change
@@ -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
```
Loading

0 comments on commit 52232ae

Please sign in to comment.