|
| 1 | +import Admonition from "@theme/Admonition"; |
| 2 | + |
| 3 | +# How to configure selectivity when running tests |
| 4 | + |
| 5 | +## Introduction |
| 6 | + |
| 7 | +Selectivity allows you to significantly speed up the testing process by running only relevant tests instead of the entire test suite. Testplane tracks each test's dependencies on project files — both the test code itself and the code executed in the browser — and, when a file changes, runs only those tests that depend on it. |
| 8 | + |
| 9 | +## How does it work? |
| 10 | + |
| 11 | +On the first run with selectivity enabled, Testplane collects dependency information for each test: |
| 12 | + |
| 13 | +- which Node.js modules were loaded while the test was running; |
| 14 | +- which source files were executed in the browser. |
| 15 | + |
| 16 | +After a file changes, on the next run only those tests that depend on the changed file will be executed. This saves a lot of time, especially in large projects with many tests. |
| 17 | + |
| 18 | +<Admonition type="info"> |
| 19 | + If at least one test fails, then on the next run all the same tests will be executed again — |
| 20 | + Testplane will "remember" the new state only after a fully successful run. |
| 21 | +</Admonition> |
| 22 | + |
| 23 | +## Setup |
| 24 | + |
| 25 | +To enable selectivity, just add a [`selectivity`](/docs/v8/config/browsers#selectivity) section with `enabled: true` to your Testplane configuration: |
| 26 | + |
| 27 | +```typescript |
| 28 | +// testplane.config.ts |
| 29 | +export default { |
| 30 | + gridUrl: "local", |
| 31 | + baseUrl: "about:blank", |
| 32 | + pageLoadTimeout: 20000, |
| 33 | + httpTimeout: 20000, |
| 34 | + testTimeout: 90000, |
| 35 | + resetCursor: false, |
| 36 | + sets: { |
| 37 | + desktop: { |
| 38 | + files: ["testplane-tests/**/*.testplane.(t|j)s"], |
| 39 | + browsers: ["chrome", "firefox"], |
| 40 | + }, |
| 41 | + }, |
| 42 | + browsers: { |
| 43 | + chrome: { |
| 44 | + headless: true, |
| 45 | + desiredCapabilities: { |
| 46 | + browserName: "chrome", |
| 47 | + }, |
| 48 | + }, |
| 49 | + firefox: { |
| 50 | + desiredCapabilities: { |
| 51 | + browserName: "firefox", |
| 52 | + }, |
| 53 | + }, |
| 54 | + }, |
| 55 | + selectivity: { |
| 56 | + enabled: true, |
| 57 | + }, |
| 58 | +} satisfies import("testplane").ConfigInput; |
| 59 | +``` |
| 60 | + |
| 61 | +## Usage example |
| 62 | + |
| 63 | +Let’s enable selectivity in a project with `chrome` and `firefox` browsers. For convenience, we’ll also configure a [devServer][dev-server]: |
| 64 | + |
| 65 | +```ts |
| 66 | +// testplane.config.ts |
| 67 | +const DEV_SERVER_PORT = 3050; |
| 68 | + |
| 69 | +export default { |
| 70 | + baseUrl: `http://127.0.0.1:${DEV_SERVER_PORT}`, |
| 71 | + // ... Other settings |
| 72 | + devServer: { |
| 73 | + command: `npm run dev -- --port=${DEV_SERVER_PORT}`, |
| 74 | + reuseExisting: true, |
| 75 | + readinessProbe: { |
| 76 | + url: `http://127.0.0.1:${DEV_SERVER_PORT}`, |
| 77 | + }, |
| 78 | + }, |
| 79 | + selectivity: { |
| 80 | + enabled: true, |
| 81 | + }, |
| 82 | +} satisfies import("testplane").ConfigInput; |
| 83 | +``` |
| 84 | + |
| 85 | +We’ll also enable SourceMap generation in the Webpack config used by the project: |
| 86 | + |
| 87 | +```js |
| 88 | +// webpack.config.js |
| 89 | +module.exports = (env, argv) => { |
| 90 | + return { |
| 91 | + // ... |
| 92 | + // Use multiple entry points |
| 93 | + entry: { |
| 94 | + main: './js/home.js', |
| 95 | + about: './js/about.js', |
| 96 | + contact: './js/contact.js', |
| 97 | + shared: './js/shared.js' |
| 98 | + }, |
| 99 | + // Enable SourceMap generation |
| 100 | + // Both external (`source-map`) and inline (`inline-source-map`) are suitable |
| 101 | + devtool: 'source-map', |
| 102 | + output: { |
| 103 | + // Specify a template that Webpack will use to store paths to source files |
| 104 | + // `[resource-path]` or `[absolute-resource-path]` will also work |
| 105 | + devtoolModuleFilenameTemplate: "webpack://[resource-path]", |
| 106 | + }, |
| 107 | +``` |
| 108 | +
|
| 109 | +For the example we’ll use a plain JavaScript project without React, with the following file structure: |
| 110 | +
|
| 111 | +``` |
| 112 | +. |
| 113 | +|____css |
| 114 | +| |____home.css |
| 115 | +| |____shared.css |
| 116 | +| |____about.css |
| 117 | +|____js |
| 118 | +| |____about.js |
| 119 | +| |____home.js |
| 120 | +| |____main.js |
| 121 | +| |____contact.js |
| 122 | +| |____shared.js |
| 123 | +|____index.html |
| 124 | +|____about.html |
| 125 | +|____contact.html |
| 126 | +|____webpack.config.js |
| 127 | +|____testplane.config.ts |
| 128 | +|____testplane-tests |
| 129 | +| |____example.testplane.ts |
| 130 | +| |____tsconfig.json |
| 131 | +|____package.json |
| 132 | +|____package-lock.json |
| 133 | +``` |
| 134 | +
|
| 135 | +Let’s write the following tests: |
| 136 | +
|
| 137 | +```ts |
| 138 | +describe("test examples", () => { |
| 139 | + it("main page", async ({ browser }) => { |
| 140 | + await browser.url("/"); |
| 141 | + }); |
| 142 | + |
| 143 | + it("main page with navigation to about page", async ({ browser }) => { |
| 144 | + await browser.url("/"); |
| 145 | + await browser.$("#about-link").click(); |
| 146 | + }); |
| 147 | + |
| 148 | + it("main page with navigation to contact page", async ({ browser }) => { |
| 149 | + await browser.url("/"); |
| 150 | + await browser.$("#contact-link").click(); |
| 151 | + }); |
| 152 | + |
| 153 | + it("contact page", async ({ browser }) => { |
| 154 | + await browser.url("/contact"); |
| 155 | + }); |
| 156 | +}); |
| 157 | +``` |
| 158 | +
|
| 159 | +And run Testplane. For clarity, we’ll use the `DEBUG=testplane:selectivity` environment variable: |
| 160 | +
|
| 161 | + |
| 162 | +
|
| 163 | +Let’s try running it again: |
| 164 | +
|
| 165 | + |
| 166 | +
|
| 167 | +When there are no changes, running all tests is skipped. |
| 168 | +
|
| 169 | +Now let’s change a couple of source files that are executed in the browser: |
| 170 | +
|
| 171 | + |
| 172 | +
|
| 173 | +Only one test that depends on the changed files was run. The rest were skipped by selectivity. |
| 174 | +
|
| 175 | +The same applies to test code selectivity: let’s create `./testplane-tests/my-module.ts`: |
| 176 | +
|
| 177 | +```ts |
| 178 | +export const foo = () => { |
| 179 | + throw new Error("bar"); |
| 180 | +}; |
| 181 | +``` |
| 182 | +
|
| 183 | +And use it in the test file: |
| 184 | +
|
| 185 | +```ts |
| 186 | +import { foo } from "./my-module"; |
| 187 | + |
| 188 | +describe("test examples", () => { |
| 189 | + it("main page", async ({ browser }) => { |
| 190 | + foo(); |
| 191 | + await browser.url("/"); |
| 192 | + }); |
| 193 | + // The rest of the tests |
| 194 | +}); |
| 195 | +``` |
| 196 | +
|
| 197 | +Now run the tests: |
| 198 | +
|
| 199 | + |
| 200 | +
|
| 201 | +While processing the test file, Testplane noticed that it now depends on another file, which means the functionality might have changed, so all tests in this file were run. |
| 202 | +
|
| 203 | +But since the tests failed, the new state was not saved, so re-running the tests will run the same set of tests again. |
| 204 | +
|
| 205 | +## Important details |
| 206 | +
|
| 207 | +### Collecting browser dependencies |
| 208 | +
|
| 209 | +Testplane records browser dependencies only in the Chrome browser, because dependency collection works via the [Chrome Devtools Protocol](/docs/v8/reference/webdriver-vs-cdp). However, if you have multiple browsers (for example, Chrome and Firefox), Firefox will still be able to use the list of browser dependencies for a test that was collected in Chrome. |
| 210 | +
|
| 211 | +### SourceMap requirement |
| 212 | +
|
| 213 | +For selectivity to work correctly, **SourceMap generation is required**. Thanks to SourceMaps, the browser can understand which source file the executed code belongs to. If a SourceMap is not generated for a code file, Testplane won’t be able to determine which source file the executed code comes from, and selectivity will not work correctly. |
| 214 | +
|
| 215 | +### Server-side code and disableSelectivityPatterns |
| 216 | +
|
| 217 | +Testplane cannot track code that runs on your server, regardless of the language it’s written in. Therefore, it’s recommended to add your server-side code to the `disableSelectivityPatterns` option — any change to files matching these patterns will disable selectivity and run all tests. |
| 218 | +
|
| 219 | +If you are using the [reactStrictMode](https://nextjs.org/docs/pages/api-reference/config/next-config-js/reactStrictMode) option of the [Next.js](https://nextjs.org/) framework, rendering pages in the browser as well will allow Testplane to account for these files as if this were a regular SPA application. However, code executed exclusively on the server (such as API request handlers) will not be considered by Testplane’s selectivity. |
| 220 | +
|
| 221 | +You should also add your Testplane configuration files (for example, `testplane.config.ts`) to `disableSelectivityPatterns`, since changing them can affect the behavior of any test. |
| 222 | +
|
| 223 | +<Admonition type="warning"> |
| 224 | + Do not add `node_modules` to `disableSelectivityPatterns` — this will significantly slow things |
| 225 | + down. Testplane tracks the used modules from `node_modules` on its own. |
| 226 | +</Admonition> |
| 227 | +
|
| 228 | +Example `disableSelectivityPatterns` configuration: |
| 229 | +
|
| 230 | +```typescript |
| 231 | +selectivity: { |
| 232 | + enabled: true, |
| 233 | + disableSelectivityPatterns: [ |
| 234 | + "testplane.config.ts", |
| 235 | + "backend/**/*.py", // server-side code in Python |
| 236 | + "server/**/*.go", // server-side code in Go |
| 237 | + ] |
| 238 | +} |
| 239 | +``` |
| 240 | +
|
| 241 | +### Manually disabling selectivity |
| 242 | +
|
| 243 | +When you use other filtering methods when running Testplane (such as specifying a path to a test file or using the `--grep` and `--set` options), selectivity is automatically disabled. |
| 244 | +
|
| 245 | +You can also disable selectivity manually using an environment variable: |
| 246 | +
|
| 247 | +```bash |
| 248 | +testplane_selectivity_enabled=false # disable |
| 249 | +``` |
| 250 | +
|
| 251 | +## Configuration |
| 252 | +
|
| 253 | +Additional information about selectivity configuration is provided in the [browsers-selectivity][selectivity-config] section of the documentation. |
| 254 | +
|
| 255 | +[dev-server]: ../../config/dev-server |
| 256 | +[selectivity-config]: ../../config/browsers#selectivity |
0 commit comments