Koulutustarjonnan virkailijan käyttöliittymä. React-kirjastolla kehitetty SPA (single page app), jonka varsinainen koodi sijaitsee hakemistossa src/main/app. Juurihakemiston Spring Boot -kääre tarjoilee SPA:n ympäristökohtaisten asetusten kanssa, kun sovellus asennetaan pilveen.
Lomakkeiden tilan hallinta on toteutettu redux-form-kirjastolla. Redux-form rekisteröi kentän kun sitä vastaava komponentti renderöidään. Vastaavasti rekisteröinti poistetaan (unregister), kun kenttää vastaava komponentti poistetaan. Näiden redux-tapahtumien avulla tunnistetaan milloin käyttäjä on poistanut kentät itse näkyvistä ja niille halutaan lähettää tyhjä arvo. Tämä onnistuu, koska unregister-tapahtumaa ei lähetetä alussa kun kenttä on piilossa.
Jotkin kyselyistä halutaan muistintaa pitkään (organisaatiopalvelu, eperusteet, koodisto jne.), ja joitakin vain hyvin lyhyen aikaa (kouta-backend). Haasteena on myös saman palvelimelta ladatun tiedon käyttäminen eri komponenteissa. Kouta-UI:ssa käytetään react-query-kirjastoa, joka tarjoaa miellyttävän abstraktion palvelinpyyntöjen hallintaan. Omien useEffect-rakennelmien tekeminen tai Reduxin käyttäminen tätä tarkoitusta varten ei ole tarpeen, eikä suotavaa.
Kehityksen aikana käyttöliittymää kannattaa ajaa pelkästään nodella, jolloin muutokset näkyvät suoraan selaimessa.
cd src/main/app
npm run start
Hetken kuluttua käyttöliittymä on käytettävissä osoitteessa (selainta ei avata automaattisesti):
Huom! HTTPS-protokolla käytössä. Webpack-dev-serverin proxy on konfiguroitu oletuksena ohjaamaan kaikki muut polut paitsi /, /kouta ja /kouta/* osoitteeseen https://virkailija.hahtuvaopintopolku.fi. Käytetään oletuksena self-signed-sertifikaatteja, eikä CORS-rajoituksia ei tarvitse kiertää selaimessa. Kehitysympäristön virkailija-osoitetta, johon proxytaan voi vaihtaa asettamalla ympäristömuuttujan DEV_VIRKAILIJA_URL eri arvoon .env.development.local-tiedostossa.
Kehittämisessä suositeltava editori on "Visual Studio Code", mutta sen käyttäminen ei ole pakollista. Hyödyllisiä VSCode-plugineja ovat mm:
- ESLint näyttää ESLint-virheet editorissa. Erillistä prettier-pluginia ei tarvita, koska ne mäpätään eslint-varoituksiksi.
- XState VSCode tarjoaa monenlaisia työkaluja xstate-tilakoneiden kanssa työskentelyyn.
- Total Typescript tekee TypeScript-virheistä helpommin ymmärrettäviä ja näyttää opettavaisia selityksiä erilaisille TypeScript-rakenteille.
- vscode-styled-components auttaa erityisesti styled-components-kirjaston CSS-template-stringien kanssa.
Käytössä on ESlint ja Prettier koodin tyylin yhdenmukaistamiseksi ja staattiseen tarkistamiseen. Prettier ajetaan eslint-sääntönä, joten prettierin ajaminen JS/TS-tiedostoille erikseen ei ole tarpeen. Lisäksi eslint ajetaan Huskyn ja Lint-staged:n avulla Git precommit-hookissa, jolloin korjataan ne virheet/varoitukset, jotka pystytään. Jos ei kaikkea pystytty korjaamaan, commit epäonnistuu ja käyttäjän täytyy korjata jäljellä olevat ongelmat käsin.
ESLintin voi ajaa käsin komennolla npm run lint, tai automaattisen fiksauksen kanssa npm run lint:fix.
Korvaa kouta-backendissä dev-vars.yml-tiedostoon:
kouta_backend_cas_service: https://localhost:3000/kouta-backend/auth/login
ja käynnistä kouta-backend (EmbeddedJettyLauncher).
Aseta kouta-ui:ssa ympäristömuuttuja (esim. .env.development.local-tiedostossa):
KOUTA_BACKEND_URL=http://localhost:8099
Käynnistä kouta-ui lokaalisti komennolla:
npm run start
Käynnistä Opintopolun VPN, jotta kouta-backend saa yhteyden käyttöoikeus-servicen userDetails-rajapintaan.
Kirjaudu selaimella linkistä http://localhost:8099/kouta-backend/auth/login
Tämän jälkeen mene selaimella osoitteeseen https://localhost:3000/kouta
Käynnistä Opintopolun VPN
Käynnistä kouta-backend sen README:ssa olevan osion (3.4.1 Ajo testiympäristöä vasten) ohjeen mukaan.
Aseta kouta-ui:ssa ympäristömuuttuja (esim. .env.local-tiedostossa):
KOUTA_BACKEND_URL=http://localhost:8099
Käynnistä kouta-ui lokaalisti komennolla:
npm run start
Kirjaudu selaimella linkistä http://localhost:8099/kouta-backend/auth/login
Mene selaimella osoitteeseen https://localhost:3000/virkailijan-tyopoyta/ ja kirjaudu.
Tämän jälkeen mene selaimella osoitteeseen https://localhost:3000/kouta
Projektin saa buildattua komennolla:
mvn clean install
Tämän jälkeen projektin voi käynnistää lokaalisti komennolla:
java -jar target/kouta-ui-0.1.0-SNAPSHOT.jar --spring.config.location=./koutaui-dev.yml
tai komennolla:
mvn spring-boot:run
Sovellus aukeaa osoitteeseen:
Jos projektia halutaan ajaa pilviympäristöä vasten, tiedostoon koutaui-dev.yml pitää vaihtaa host-virkailija
osoittamaan oikeaan ympäristöön. Lisäksi CORSin pystyy kiertämään käynnistämällä Chrome (macissa) komennolla:
open -a Google\ Chrome --args --disable-web-security --user-data-dir=/tmp/moi
Yksikkötestit on toteutettu Jest-kirjastolla. Ne löytyvät testattavan moduulin *.test.jsx? (esim. components/Input/Input.test.jsx) tiedostosta, ja ne voi ajaa komennolla npm run test.
Koko sovellusta vasten ajettavat testit on toteutettu Playwright-kirjastolla. Ensimmäisellä kerralla, ja aina kun Playwright-riippuvuus päivittyy, täytyy sen käyttämät selaimet riippuvuuksineen asentaa käsin komennolla:
npx playwright install
Playwright-testit olettavat kälin löytyvän ajossa portista 3000 (ks. otsikko "Käyttöliittymän kehittäminen" yllä).
Jos haluat ajaa kaikki testit kannattaa tehdä kuten Github Actionsissa, eli buildata ja servata sovellus:
npm run build:test
npm run serve:test
ja ajaa sitten kaikki testit toisessa terminaalissa komennolla
npx playwright test
Playwright-testejä voi ajaa myös dev-serveriä vasten, mutta se on paljon hitaampaa kuin servattua tuotanto-buildia vasten. Aikakatkaisuja voi tulla, vaikka rajoja on kasvatettu. Playwright-testit olettavat, että sovellus on renderöity käyttäen käännösavaimia, minkä vuoksi on käytettävä npm run start:integrationtai npm run start:integration:debug komentoa dev-serverin käynnistämiseen. NPM-skripti start:integration:debug eroaa start:integration:sta siten, että se sallii sovelluksen kyselyt ulkopuolelle, jolloin sovellusta voi testailla selaimella muutenkin. Tällöin täytyy kuitenkin olla tarkkana, että muistaa lisätä fixtuurit tarvittaville API-kyselyille.
Kun sovellus on ajossa, kätevintä yksittäisten Playwright-testien ajaminen ja debuggaminen on käyttämällä "Visual Studio Code"-editorissa virallista Playwright-pluginia: https://playwright.dev/docs/getting-started-vscode
Yksittäisiä testejä voi myös ajaa Playwrightin UI-moodissa, jonka saa käynnistettyä komennolla:
npx playwright test --ui
Storybookin voi käynnistää komennolla npm run storybook. Käynnistymisen jälkeen Storybook löytyy osoitteesta http://localhost:9009. Komponenttien mahdolliset storyt löytyvät komponentin oman kansion *.stories.jsx (esim. components/Alert/Alert.stories.jsx) tiedostosta. Hyödyllisiä story dekoraattoreita (esim. lokalisaatio- ja api-dekoraattorit) löytyy storybookUtils.js tiedostosta.
Lokalisointiin käytetään react-i18next kirjastoa, joka puolestaa käyttää i18next kirjastoa. React-komponenttien sisällä käytössä on useTranslation-hook. Käännökset haetaan lokalisaatio-service:ltä kouta-kategoriasta. Suomenkieliset käännökset on määritelty translations/fi.js-tiedostossa. Käännöksissä käytetään ensisijaisesti lokalisaatio-service:n tarjoamia käännöksiä. Uusien käännöksien lisäämisen kannattaa aloittaa lisäämällä suomenkielinen käännös translations/fi.json-tiedostoon.
types/kouta-backend.api.ts on autogeneroitu kouta-backendin swaggerista openapi-typescript-kirjastolla. Jos teet muutoksia backendin tyypityksiin, päivitä tiedosto halutusta backend-ympäristöstä (ml. lokaali):
npx openapi-typescript https://virkailija.hahtuvaopintopolku.fi/kouta-backend/swagger/swagger.yaml -o ./src/types/kouta-backend.api.ts