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:integration
tai 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