@oslokommune/punkt-testing-utils 12.27.8 → 12.27.10

package/README.md

@@ -1,16 +1,58 @@
-# punkt-testing-library
+# punkt-testing-utils
 
 Dette biblioteket oppstod for å gjøre det enklere å skrive frontend-tester i applikasjoner som bruker Punkt og testing-library.
 
-Siden testing-library ikke har veldig god støtte for custom elements (web components). Når du oppgraderer til ny Punkt-versjon, og Punkt-teamet har migrert komponenter fra React/Vue til Web components, risikerer du at testene dine begynner å feile på ikke-opplagt vis.
+testing-library ikke har veldig god støtte for custom elements (web components). Når du oppgraderer til ny Punkt-versjon, og Punkt-teamet har migrert komponenter fra React/Vue til Web components, risikerer du at testene dine begynner å feile på ikke-opplagt vis.
 
-punkt-testing-library er ment å gjøre oppgradering til nye Punkt-versjoner mindre smertefullt, ved å abstrahere funksjoner fra testing-library og la deg som webapp-utvikler forholde deg til funksjoner som vedlikeholdes av Punkt.
+punkt-testing-utils er ment å gjøre oppgradering til nye Punkt-versjoner mindre smertefullt, ved å abstrahere funksjoner fra testing-library og la meg som webapp-utvikler forholde meg til funksjoner som vedlikeholdes av Punkt.
+
+## Eksempel:
+I Team Booking har vi en haug med tester på frontend-koden vår. Disse er skrevet i react-testing-library, og er dermed typisk noe sånt:
+
+### Uten punkt-testing-library
+```
+render()
+const input = screen.getByRole("textbox", "Skriv her")
+fireEvent.change(input, "Noe tekst")
+const submitButton = screen.getByLabelText("button", "Send inn")
+fireEvent.click(button);
+// Assert at noe er sendt inn
+```
+
+Dette funker fint så lenge `getByRole` finner en `<input/>` og en `<button/>`, sånn at verdien blir satt og knappen trykket på, og det har fungert så lenge Punkt-komponentene har vært enkle React-komponenter.
+
+Men etterhvert som Punkt skrives om til custom elements, holder ikke lenger den forutsetningen. En `getByRole` kan nå ende opp med å finne punkt-textinput sin interne, skjulte `<input>`, som ikke er ment å herjes med.
+react-testing-library gir ikke noe gratis mtp custom elements.
+
+Så hver gang vi har oppdatert webappen vår til ny Punkt-versjon, har en haug av testene våre brukket, og det har vært mye jobb med å fikse dem, **hver gang**.
+
+### Med punkt-testing-library
+```
+const input = ptl.getPktElementByLabelText("Skriv her"); // ptl = punkt-testing-library
+await ptl.setPktElementValue(input, "Noe tekst");
+const submitButton = screen.getByLabelText("button", "Send inn")
+await ptl.pktClickButton(submitButton);
+// Assert at noe er sendt inn
+
+```
+Dette er mindre sårbart fordi vi ikke trenger å vite om input-feltet er et `PktTextinput` eller et `HTMLInput`-element - så lenge vi holder oss til funksjoner fra punkt-testing-library, vil testene våre fungere uavhengig av hvilken versjon av Punkt vi bruker.
+
+Funksjonene i punkt-testing-library støtter både gamle (ikke-custom-elements) og nye (custom elements) versjoner av Punkt-komponentene, sånn at testene ikke brekker når Punkt bytter implementasjon av komponentene sine. punkt-testing-library er i seg selv dekket av tester, og bor i kodebasen til Punkt, så Team Designsystem vil tidlig oppdage tidlig om de har endret noe som gjør at noe brekker.
+
+Etter å ha skrevet om testene våre en siste (🤞) gang, denne gang til å bruke punkt-testing-library, har det vært (så godt som) smertefritt å bytte Punkt-versjon i webappen vår.
+
+Funksjoner i punkt-testing-library som tar et element som parameter, kan også kalles med label, så eksempelet kan forkortes til
+```
+await setPktElementValue('Skriv her', 'Noe tekst');
+await pktClickButton('Send inn');
+```
+Merk at funksjoner i punkt-testing-library som endrer verdier eller trigger events er asynkrone (returnerer et promise), så de bør alltid brukes med `await`.
 
 ## Installasjon og oppsett
 ```
-npm install --save-dev @oslokommune/punkt-testing-library
+npm install --save-dev @oslokommune/punkt-testing-utils
 ```
-Du må initialisere punkt-testing-library med din testing-library-implementasjon, for eksempel:
+Du må initialisere punkt-testing-library med din testing-library-implementasjon, med react-testing-library blir det sånn:
 ```
 import * as ReactTestingLibrary from '@testing-library/react';
 
@@ -22,65 +64,28 @@ const {
   getPktElementByPlaceholderText,
   waitForPktElementsToBeDefined,
   getPktSelectOptions,
-  checkPktElement,
 } = setupPktTestingLibrary(ReactTestingLibrary)
 ```
 Dette kan du gjerne gjøre i en felles-fil som du importerer i testene dine.
 
-## Eksempel:
-
-### Uten punkt-testing-library
-```
-const input = (await screen.findByLabelText("Mitt input-felt"));
-fireEvent.change(input, "Ny verdi");
- ```
-Dette er sårbart fordi `findByLabelText` kan returnere et `PktTextinput` eller det underliggende `HTMLInput`-elementet, avhengig av hvilken versjon av Punkt du bruker.
-
-### Med punkt-testing-library
-```
-const input = punktTestingLibrary.getPktElementByLabelText('Mitt input-felt');
-await punktTestingLibrary.changePktElementValue(input, 'Ny verdi');
-```
-Dette er mindre sårbart fordi du ikke trenger å vite om input-feltet er et `PktTextinput` eller et `HTMLInput`-element - så lenge du holder deg til funksjoner fra punkt-testing-library, vil testene dine fungere uavhengig av hvilken versjon av Punkt du bruker.
-
-Funksjoner i punkt-testing-library som tar et element som parameter, kan også kalles med label, så eksempelet kan forkortes til
-```
-const element = await punktTestingLibrary.setPktElementValue('Mitt input-felt', 'Ny verdi');
-```
-Merk at funksjoner i punkt-testing-library som endrer verdier er asynkrone (returnerer et promise), så de bør alltid brukes med `await`.
-
 ## API
 ```
-export type LabelOrElement = string | RegExp | Element
-
-/**
- * Representerer en option i en PktSelect.
- *
- * @property {string} 0 - verdien (value)
- * @property {string | null} 1 - Tekstinnholdet, <option>tekstinnhold</option>
- * @property {boolean} 2 - Om denne er valgt (selected)
- */
+type PktElementType = PktDatepicker | PktProgressbar | PktTextarea | PktInputWrapper | PktSelect | PktRadioButton;
+export declare const waitForPktElementsToBeDefined: () => Promise<(CustomElementConstructor | undefined)[]>;
+export declare const getPktElementByLabelText: (label: string, container?: HTMLElement) => PktElementType;
+export declare function setPktElementValue(element: PktElementType, valueOrValues: string | Array<string>): Promise<boolean>;
+export declare const setPktElementChecked: (element: PktElementType, checked: boolean) => Promise<boolean>;
 type PktOption = [string, string | null, boolean];
-
-export type PktTestingLibrary = {
-  checkPktElement: (labelOrElement: LabelOrElement) => Promise<boolean>
-  getPktElementByLabelText: (label: string, container?: HTMLElement) => Element
-  getPktElementByPlaceholderText: (labelOrElement: LabelOrElement) => Element
-  getPktSelectOptions: (labelOrElement: LabelOrElement<PktSelect>) => Array<PktOption>
-  getAllPktElementsByLabelText: (label: string, container?: HTMLElement) => Element[]
-  setPktElementChecked: (labelOrElement: LabelOrElement, checked: boolean) => Promise<boolean>
-  setPktElementValue: (
-    labelOrElement: LabelOrElement,
-    valueOrValues: string | Array<string>,
-    useInputEvent?: boolean,
-  ) => Promise<boolean>
-  pktClickButton: (labelOrElement: LabelOrElement) => Promise<boolean>
-  waitForPktElementsToBeDefined: () => Promise<any>
-}
+export declare const getPktSelectOptions: (selectElement: PktSelect) => Array<PktOption>;
+export declare const setPktSelectedOptionsByLabel: (selectElement: PktElementType | HTMLSelectElement, ...optionLabels: Array<string>) => Promise<boolean>;
+export declare const checkPktElement: (element: PktRadioButton) => Promise<boolean>;
+export declare const getAllPktElementsByLabelText: (label: string, container?: HTMLElement) => Element[];
+export declare const getPktElementByPlaceholderText: (container: Element, placeholder: string) => Element;
 ```
 
-## Er dette bare for React?
-Nja - foreløpig er punkt-testing-library bare testet med react-testing-library. Bruker Punkt med Vue? Det _kan_ det hende at mye vil fungere med vue-testing-library også. Hvis du prøver, så gi oss gjerne tilbakemelding, så er vi interesserte i å få det til å funke!
+## Men vent! Er dette bare for React? Hva med Vue? Svelte? Cypress? Playwright?
+Foreløpig har vi ikke gjort noe for å støtte Vue, men det er en liten, teoretisk sjanse for at det funker ut av boksen. punkt-testing-library har en dependency til dom-testing-library, men ikke til react-testing-library. Du kan plugge inn ditt favoritt (testing-library-kompatible) test-bibliotek, for eksempel vue-testing-library og håpe at det funker - men det har vi som sagt ikke testa, ennå. Men prøv gjerne, og se hvor det tryner, så kan vi fikse det i fellesskap.
+Hvis du bruker et testbibliotek som ikke er basert på testing-library, må du implementere en del funksjoner selv. I så fall kan det være best å kopiere koden lage et nytt testbibliotek.
 
 Det kan også være mulig å bruke punkt-testing-library med helt andre testrammeverk. Du må i så fall implementere `PktTestingLibraryOptions`-interfacet selv, og initialisere punkt-testing-library med din implementasjon:
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oslokommune/punkt-testing-utils",
-  "version": "12.27.8",
+  "version": "12.27.10",
   "description": "Test-utilities for Punkt",
   "homepage": "https://punkt.oslo.kommune.no",
   "author": "Team Designsystem, Oslo Origo",
@@ -17,8 +17,8 @@
     "element-internals-polyfill": "^1.3.10"
   },
   "devDependencies": {
-    "@oslokommune/punkt-elements": "^12.27.7",
-    "@oslokommune/punkt-react": "^12.27.7",
+    "@oslokommune/punkt-elements": "^12.27.9",
+    "@oslokommune/punkt-react": "^12.27.9",
     "@testing-library/jest-dom": "^6.1.0",
     "@types/jest": "^29.5.0",
     "@types/testing-library__jest-dom": "^5.14.9",
@@ -65,5 +65,5 @@
     "url": "https://github.com/oslokommune/punkt/issues"
   },
   "license": "MIT",
-  "gitHead": "c6df591fffd757aa56122b1897e79cdf11649d06"
+  "gitHead": "9a1c0b685b7d0358ef4f0b6c41344221bec593e3"
 }