From 8472d33f7d5722fef36b5054c54e06231c3d73fc Mon Sep 17 00:00:00 2001
From: patak <matias.capeletto@gmail.com>
Date: Wed, 14 Apr 2021 19:40:20 +0200
Subject: [PATCH] docs: contributing.md extending test suite section (#2946)

---
 .github/contributing.md | 34 +++++++++++++++++++++++++++++++++-
 1 file changed, 33 insertions(+), 1 deletion(-)

diff --git a/.github/contributing.md b/.github/contributing.md
index d0b3e4f9..49f52829 100644
--- a/.github/contributing.md
+++ b/.github/contributing.md
@@ -29,7 +29,7 @@ Each test can be run under either dev server mode or build mode.
 
 - You can also use `yarn test-serve [match]` or `yarn test-build [match]` to run tests in a specific playground package, e.g. `yarn test-serve css` will run tests for both `playground/css` and `playground/css-codesplit` under serve mode.
 
-  Note package matching is not aviable for the `yarn test` script, which always runs all tests.
+  Note package matching is not available for the `yarn test` script, which always runs all tests.
 
 ### Test Env and Helpers
 
@@ -43,6 +43,38 @@ test('should work', async () => {
 
 Some common test helpers, e.g. `testDir`, `isBuild` or `editFile` are available in `packages/playground/testUtils.ts`.
 
+### Extending the Test Suite
+
+To add new tests, you should find a related playground to the fix or feature (or create a new one). As an example, static assets loading are tested in the [assets playground](https://github.com/vitejs/vite/tree/main/packages/playground/assets). In this Vite App, there is a test for `?raw` imports, with [a section is defined in the `index.html` for it](https://github.com/vitejs/vite/blob/71215533ac60e8ff566dc3467feabfc2c71a01e2/packages/playground/assets/index.html#L121):
+
+```html
+<h2>?raw import</h2>
+<code class="raw"></code>
+```
+
+This will be modified [with the result of a file import](https://github.com/vitejs/vite/blob/71215533ac60e8ff566dc3467feabfc2c71a01e2/packages/playground/assets/index.html#L151):
+
+```js
+import rawSvg from './nested/fragment.svg?raw'
+text('.raw', rawSvg)
+```
+
+Where the `text` util is defined as:
+
+```js
+function text(el, text) {
+  document.querySelector(el).textContent = text
+}
+```
+
+In the [spec tests](https://github.com/vitejs/vite/blob/71215533ac60e8ff566dc3467feabfc2c71a01e2/packages/playground/assets/__tests__/assets.spec.ts#L180), the modifications to the DOM listed above are used to test this feature:
+
+```js
+test('?raw import', async () => {
+  expect(await page.textContent('.raw')).toMatch('SVG')
+})
+```
+
 ## Pull Request Guidelines
 
 - Checkout a topic branch from a base branch, e.g. `main`, and merge back against that branch.