@telefonica/acceptance-testing 3.0.0-beta9 → 4.0.0

package/README.md

@@ -251,29 +251,68 @@ await elementHandle.uploadFile(prepareFile('/path/to/file'));
 
 ## Collecting coverage
 
-This library automatically collects code coverage after each test by reading the `window.__coverage__` object
-if available.
+Set the `COLLECT_ACCEPTANCE_COVERAGE` environment variable to enable coverage collection.
 
-To create that object you should instrument the code with an `istanbul` compatible tool (for example
-[babel-plugin-istanbul](https://github.com/istanbuljs/babel-plugin-istanbul)).
+The code must be instrumented with [nyc](https://github.com/istanbuljs/nyc/blob/main/docs/instrument.md),
+[babel-plugin-istanbul](https://github.com/istanbuljs/babel-plugin-istanbul) or any
+[istanbul](https://github.com/istanbuljs/istanbuljs) compatible tool.
 
-The coverage report for each test will be saved as `json` files. To change the destination folder, set the
-`coveragePath` property in your config. The default value is `reports/coverage-acceptance`.
+### Frontend coverage information
+
+After each test the coverage information will be collected by reading the `window.__coverage__` object from
+the opened page.
+
+### Backend coverage information
+
+To collect coverage from your backend, you must create an endpoint that serves the coverage information and
+specify it the `coverageUrls` property in your config. The library will make a `GET` request to each URL and
+save the report from the response as a `json` file. The default value is `[]`.
+
+The backend coverage will be collected after all the tests in the suite have run.
+
+The response must be a JSON with the following structure: `{coverage: data}`.
+
+Example route in NextJS to serve coverage information:
+
+```ts
+import {NextResponse} from 'next/server';
+
+export const GET = (): NextResponse => {
+  const coverage = (globalThis as any).__coverage__;
+  if (coverage) {
+    return NextResponse.json({coverage});
+  }
+  return NextResponse.json({error: 'Not found'}, {status: 404});
+};
+
+export const dynamic = 'force-dynamic';
+```
+
+### Configuration
+
+The coverage information will be saved as `json` files. To change the destination folder, set the
+`coveragePath` property in your config. The default value is `reports/coverage-acceptance`. The `json` files
+will be stored inside `<coveragePath>/.nyc_output`.
 
 Example config:
 
 ```json
 {
   "acceptanceTests": {
-    "coveragePath": "coverage/acceptance"
+    "coveragePath": "coverage/acceptance",
+    "coverageUrls": ["http://localhost:3000/api/coverage"]
   }
 }
 ```
 
-After running the tests, you can use a tool like `nyc` to generate the coverage summaries.
+### Generate coverage reports
+
+After running the tests, you can use a tool like `nyc` to generate the coverage reports.
 
 ## Troubleshooting
 
+### Unhandled browser errors
+
 If you see an acceptance test failing without any apparent reason, it could be caused by an unhandled error in
 the browser. You can inspect it by adding a listener to the `pageerror` event:
 
@@ -283,3 +322,28 @@ page.on('pageerror', (err) => {
   process.emit('uncaughtException', err);
 });
 ```
+
+### Executing with --ui fails (Linux)
+
+If your desktop environment uses Wayland, you may see the following error when running the tests with the
+`--ui` flag:
+
+```
+Error: Jest: Got error running globalSetup - /home/pladaria/bra/mistica-web/node_modules/jest-environment-puppeteer/setup.js, reason: ErrorEvent {
+  "error": [Error: socket hang up],
+  "message": "socket hang up",
+  ...
+```
+
+To workaround this issue, you can install a newer Chrome in the repo where you are using the
+`acceptance-testing` library:
+
+- From the repo root: `npx @puppeteer/browsers install chrome@stable`
+- Remove the chrome installed by puppeteer:
+  `rm -rf node_modules/puppeteer/.local-chromium/linux-901912/chrome-linux`
+- Move downloaded chrome to the expected location:
+  `mv chrome/linux-<version>/chrome-linux64 node_modules/puppeteer/.local-chromium/linux-901912/chrome-linux`
+- Cleanup. Remove chrome folder from the repo root: `rm -rf chrome`
+
+Note that this browser will only be used when running the tests with the `--ui` flag. In headless mode, the
+dockerized chromium will be used.