mirror of
https://github.com/ionic-team/ionic-framework.git
synced 2025-08-14 08:45:20 +08:00
b315b0cb29
Start your review here 👉 [docs/README.md](https://github.com/ionic-team/ionic-framework/blob/FW-6107/docs/README.md) ## What is the current behavior? Documentation files with information on how to contribute, component implementations, testing, etc. are scattered throughout various folders in this repository. ## What is the new behavior? Consolidates the documentation files into a root `docs/` directory for easier discovery and organization. `/docs` tree: ``` ├── _config.yml ├── component-guide.md ├── CONTRIBUTING.md ├── README.md ├── sass-guidelines.md ├── angular │ ├── README.md │ └── testing.md ├── core │ ├── README.md │ └── testing │ ├── README.md │ ├── api.md │ ├── best-practices.md │ ├── preview-changes.md │ └── usage-instructions.md ├── react │ ├── README.md │ └── testing.md ├── react-router │ ├── README.md │ └── testing.md ├── vue │ ├── README.md │ └── testing.md └── vue-router ├── README.md └── testing.md ``` **Migrates the following:** | Previous Location | New Location | | ----------------------------------------------------------- | ----------------------------------------- | | `.github/COMPONENT-GUIDE.md` | `docs/component-guide.md` | | `.github/CONTRIBUTING.md` | `docs/CONTRIBUTING.md` | | `core/scripts/README.md` | `docs/core/testing/preview-changes.md` | | `core/src/utils/test/playwright/docs/api.md` | `docs/core/testing/api.md` | | `core/src/utils/test/playwright/docs/best-practices.md` | `docs/core/testing/best-practices.md` | | `core/src/utils/test/playwright/docs/README.md` | `docs/core/testing/README.md` | | `core/src/utils/test/playwright/docs/usage-instructions.md` | `docs/core/testing/usage-instructions.md` | | `packages/angular/test/README.md` | `docs/angular/testing.md` | | `packages/react-router/test/README.md` | `docs/react-router/testing.md` | | `packages/react/test/README.md` | `docs/react/testing.md` | | `packages/react/test/base/README.md` | `docs/react/testing.md` | | `packages/vue/test/README.md` | `docs/vue/testing.md` | **Adds the following:** | File | Description | | ----------------------------- | ----------------------------------------------------------------------- | | `docs/sass-guidelines.md` | Sass Variable guidelines taken from `ionic-framework-design-documents` | | `docs/README.md` | Entry file that should link to all other files | | `docs/_config.yml` | Config file for use with GitHub pages | | `docs/core/README.md` | Description of core, links to contributing and testing | | `docs/angular/README.md` | Description of angular, links to contributing and testing | | `docs/react/README.md` | Description of react, links to contributing and testing | | `docs/react-router/README.md` | Description of react-router, links to contributing and testing | | `docs/vue/README.md` | Description of vue, links to contributing and testing | | `docs/vue-router/README.md` | Description of vue-router, links to contributing and testing | | `docs/vue-router/testing.md` | Testing file for vue-router, populated from vue-router's main README | **Does not** add any files for `angular-server`. This is because the README is essentially empty and there is no testing in that directory. I can add blank files if we want to have something to add to later. **Does not** migrate the content of the packages' root `README.md` files. These files are used for their npm package descriptions so we should not edit them. ## Hosting Documentation We can (and should) host these files using GitHub Pages. I have duplicated them in a personal repository to see how this would look: [docs-consolidation](https://brandyscarney.github.io/docs-consolidation/). Doing so will require some formatting fixes (see [Sass Guidelines](https://brandyscarney.github.io/docs-consolidation/sass-guidelines.html#-reusable-values)) so I did not publish them now but we can easily enable GitHub pages by toggling a setting in this repository. ## Other information - Verify that no documentation files were missed in the migration - You can use these commands to search for `*.md` files in a directory: - `find core/src -type f -name "*.md" -print` - `find packages/angular -type f -name "*.md" -not -path "**/node_modules/*" -print` - I did add some redirect links in some of the existing markdown files so they might still exist for that reason - We should probably break up the contributing + component guide documentation into smaller files, such as including best practices, but I wanted to get everything in the same place first - The contributing has sections on each of the packages that we could move to that package's docs folder: https://github.com/ionic-team/ionic-framework/blob/main/.github/CONTRIBUTING.md#core --------- Co-authored-by: Maria Hutt <thetaPC@users.noreply.github.com>
59 lines
3.6 KiB
Markdown
59 lines
3.6 KiB
Markdown
# Vue Testing
|
|
|
|
Ionic Framework supports multiple versions of Vue. As a result, we need to verify that Ionic works correctly with each of these Vue versions.
|
|
|
|
## Syncing Local Changes
|
|
|
|
The Vue test app supports syncing your locally built changes for validation.
|
|
|
|
1. [Build](../README.md#building) the `core`, `packages/vue`, and `packages/vue-router` projects using `npm run build`.
|
|
2. [Build the Vue test app](#test-app-build-structure).
|
|
3. Navigate to the built test app directory (e.g. `packages/vue/test/build/vue3`).
|
|
4. Install dependencies using `npm install`.
|
|
5. Sync your local changes using `npm run sync`.
|
|
|
|
From here you can either build the application or start a local dev server. When re-syncing changes, you will need to wipe the build cache in `node_modules/.cache` and restart the dev server/re-build.
|
|
|
|
## Test App Build Structure
|
|
|
|
> [!NOTE]
|
|
> Please confirm your current directory as `packages/vue/test` before proceeding with any of the following commands.
|
|
|
|
Unlike other test applications, these test apps are broken up into multiple directories. These directories are then combined to create a single application. This allows us to share common application code, tests, etc so that each app is being tested the same way. Below details the different pieces that help create a single test application.
|
|
|
|
**apps** - This directory contains partial applications for each version of Vue we want to test. Typically these directories contain new `package.json` files, `jest.config.js` files, and more. If you have code that is specific to a particular version of Vue, put it in this directory.
|
|
|
|
**base** - This directory contains the base application that each test app will use. This is where tests, application logic, and more live. If you have code that needs to be run on every test app, put it in this directory.
|
|
|
|
**build** - When the `apps` and `base` directories are merged, the final result is put in this directory. The `build` directory should never be committed to git.
|
|
|
|
**build.sh** - This is the script that merges the `apps` and `base` directories and places the built application in the `build` directory.
|
|
|
|
Usage:
|
|
|
|
```shell
|
|
# Build a test app using apps/vue3 as a reference
|
|
./build.sh vue3
|
|
```
|
|
|
|
## How to modify test apps
|
|
|
|
To add new tests, components, or pages, modify the `base` project. This ensures that tests are run for every tested version.
|
|
|
|
If you want to add a version-specific change, add the change inside of the appropriate projects in `apps`. Be sure to replicate the directory structure. For example, if you are adding a new E2E test file called `test.e2e.ts` in `apps/vue3`, make sure you place the file in `apps/vue3/tests/e2e/test.e2e.ts`.
|
|
|
|
### Version-specific tests
|
|
|
|
If you need to add E2E tests that are only run on a specific version of the JS Framework, replicate the `VersionTest` component on each partial application. This ensures that tests for framework version X do not get run for framework version Y.
|
|
|
|
## Adding New Test Apps
|
|
|
|
As we add support for new versions of Vue, we will also need to update this directory to test against new applications. The following steps can serve as a guide for adding new apps:
|
|
|
|
1. Navigate to the built app for the most recent version of Vue that Ionic tests.
|
|
2. Update the application to the latest version of Vue.
|
|
3. Make note of any files that changed during the upgrade (`package.json`, `package-lock.json`, etc).
|
|
4. Copy the changed files to a new directory in `apps`.
|
|
5. Add a new entry to the matrix for `test-core-vue` in `./github/workflows/build.yml`. This will allow the new test app to run against all PRs.
|
|
6. Commit these changes and push.
|