dh-auth-library 1.6.1 → 2.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,63 +1,233 @@
1
- # DH Authorizatoin Library
1
+ # DH Authorization Library
2
2
 
3
- A Playwright library for all login implementations in Den Haag
3
+ A Playwright library for all logins used by Den Haag applications: AD, DigiD and eHerkenning.
4
+ It logs in, stores the session and keeps it alive during a test run, so each repository doesn't
5
+ need its own login implementation.
4
6
 
5
- it is published an npm package too and should be imported like that
7
+ It is published as an npm package.
6
8
 
7
9
  ---
8
10
 
9
- ## How to use this library
10
-
11
- Install with npm or pnpm
11
+ ## Install
12
12
 
13
+ ```bash
14
+ pnpm add dh-auth-library
15
+ # or
13
16
  npm install dh-auth-library
17
+ ```
14
18
 
15
- OR
19
+ `@playwright/test` (1.60 or later) is a peer dependency.
16
20
 
17
- pnpm add dh-auth-library
21
+ ---
22
+
23
+ ## Environment variables
24
+
25
+ The library reads these from the environment (for example from a `.env` file that your Playwright
26
+ config loads):
27
+
28
+ | Variable | Used for |
29
+ |---|---|
30
+ | `ENV` | The environment: `ACC`, `TEST`, `PROD` or `LOCALHOST`. Part of the session file names; on `LOCALHOST` DigiD and eHerkenning use the local login. |
31
+ | `PORTAL_BASE_URL` | The klantportaal. Start page of a login when the handler has no `startUrl`, and the page the session refresh checks. |
32
+ | `WITH_AD_SESSION` | `true` to start every login from an AD session, needed when the apps sit behind the AD login (outside the network). |
33
+ | `AD_USER`, `AD_PASSWORD` | The AD account used for that AD session. |
34
+ | `AD_SECRET` | The TOTP secret of the AD account's authenticator; the AD login generates the MFA code from it. |
35
+ | `SESSIONS_DIR` | Where session files are stored. Defaults to `./sessions`. |
36
+ | `DIGID_GEMACHTIGDE_USER`, `DIGID_GEMACHTIGDE_PASSWORD` | Only for `DigidLoginPage.loginAsDigidGemachtigde`. |
37
+
38
+ ---
39
+
40
+ ## Usage
41
+
42
+ A login has two parts:
43
+
44
+ - **The app**: where the login starts, which button starts it and which cookie banner to accept.
45
+ This is the same for every user, so you create a **login handler** once per app.
46
+ - **The user**: a **`TestProfile`** with the account and its auth type.
47
+
48
+ `getSessionHandler(testProfile, loginHandler)` combines them, and `SessionManager.getOrCreateSession`
49
+ gives you a session file: it logs in when there is none, reuses it while it is younger than
50
+ `MAX_SESSION_TIME_IN_MINUTES`, and refreshes it after that.
51
+
52
+ ```ts
53
+ import { ADLoginHandler, DigidLoginHandler, getSessionHandler, MAX_SESSION_TIME_IN_MINUTES, TestProfile } from 'dh-auth-library';
54
+ import { SessionManager } from 'nl-portal-playwright-libraries';
55
+
56
+ // Login handlers, once per app
57
+ export const gzacAd = new ADLoginHandler('https://alg-zgw.acc.denhaag.nl');
58
+
59
+ export const klantportaalDigid = new DigidLoginHandler({
60
+ // no startUrl: starts from PORTAL_BASE_URL
61
+ loginButton: (page) => page.locator('#oidc-digid'),
62
+ cookieButton: (page) => page.locator('#ppms_cm_agree-to-all'),
63
+ });
64
+
65
+ export const openFormsDigid = new DigidLoginHandler({
66
+ // the page that has the login button
67
+ startUrl: 'https://openformulieren-zgw.acc.denhaag.nl/<form>/startpagina',
68
+ loginButton: (page) => page.getByRole('link', { name: 'Inloggen met DigiD' }),
69
+ // accepts the app's cookie banner after login, so the consent is saved in the session;
70
+ // left out, no cookie banner is accepted
71
+ cookieButton: (page) => page.locator('button[class*="cookie-notice__accept"]'),
72
+ });
73
+
74
+ // Test users only describe the user
75
+ export const digidUser1: TestProfile = {
76
+ accountId: 'digid-user-1',
77
+ authType: 'digid',
78
+ account: { username: `${process.env.DIGID_USER}`, password: `${process.env.DIGID_PASSWORD}` },
79
+ };
80
+
81
+ // In a fixture or test: the same user in two apps
82
+ const klantportaalSession = await SessionManager.getOrCreateSession(
83
+ browser,
84
+ getSessionHandler(digidUser1, klantportaalDigid),
85
+ MAX_SESSION_TIME_IN_MINUTES,
86
+ );
87
+ const context = await browser.newContext({ storageState: klantportaalSession });
88
+ ```
89
+
90
+ | Login handler | Options |
91
+ |---|---|
92
+ | `ADLoginHandler(targetUrl)` | The app behind the AD login to open, e.g. GZAC. |
93
+ | `DigidLoginHandler`, `DigidGemachtigdeLoginHandler` | `loginButton` (required): the app's DigiD button. `startUrl` (optional): defaults to `PORTAL_BASE_URL`. `cookieButton` (optional). |
94
+ | eHerkenning handlers | No options yet: they always use the klantportaal (see [Known limitations](#known-limitations)). |
95
+
96
+ `loginButton` and `cookieButton` are functions because the page doesn't exist yet when the handler is
97
+ created. A DigiD handler without `loginButton` is a compile error.
98
+
99
+ `getLoginHandler(authType, options)` creates the same handlers from an auth type, e.g.
100
+ `getLoginHandler('ad-session', { startUrl })`, and checks the required options at runtime.
101
+ `getSessionHandler(testProfile)` without a handler uses it, which works for auth types that need no
102
+ options (eHerkenning, localhost).
103
+
104
+ The login pages can also be used directly, with the same options:
105
+
106
+ ```ts
107
+ import { DigidLoginPage } from 'dh-auth-library';
108
+
109
+ const digidLoginPage = new DigidLoginPage(page);
110
+ await digidLoginPage.loginAndCreateNewSession(digidUser1.account, 'digid-session.json', {
111
+ startUrl: 'https://openformulieren-zgw.acc.denhaag.nl/<form>/startpagina',
112
+ loginButton: (page) => page.getByRole('link', { name: 'Inloggen met DigiD' }),
113
+ });
114
+ ```
18
115
 
19
116
  ---
20
117
 
21
- ## 📦 Purpose
118
+ ## Upgrading from 1.x
119
+
120
+ 2.0 has breaking changes:
121
+
122
+ | 1.x | 2.0 |
123
+ |---|---|
124
+ | `getSessionHandler(digidUser)` | `getSessionHandler(digidUser, new DigidLoginHandler({ loginButton, cookieButton }))` |
125
+ | `getSessionHandler(adUser, url)` | `getSessionHandler(adUser, new ADLoginHandler(url))` |
126
+ | `getLoginHandler('ad-session', url)` | `getLoginHandler('ad-session', { startUrl: url })` |
127
+ | DigiD clicked the klantportaal buttons and cookie banner by default | Pass `loginButton` (required) and `cookieButton` |
128
+ | Dutch method and field names, e.g. `accepteerCookies`, `klikOpDigidLoginOptie`, `*LoginKnop` | English: `acceptCookies`, `clickDigidLoginOption`, `*LoginButton` |
129
+ | `loginAlsDigidGemachtigde()` | `loginAsDigidGemachtigde(loginButton)`: the DigiD machtigen button is now required, e.g. `page.locator('#digid-machtigen')` |
22
130
 
23
- Within DenHaag we will have several different repositories which will all have to use certain
24
- types of login like AD, digid and eHerkenning.
131
+ For the klantportaal, the 1.x DigiD behaviour is:
25
132
 
26
- In order to prevent each repo to have it's own implementation we created this library which
27
- will take care of all login logic and even maintains the sessions during the testrun
133
+ ```ts
134
+ new DigidLoginHandler({
135
+ loginButton: (page) => page.locator('#oidc-digid'), // '#digid-machtigen' for DigiD machtigen
136
+ cookieButton: (page) => page.locator('#ppms_cm_agree-to-all'),
137
+ });
138
+ ```
28
139
 
29
140
  ---
30
141
 
31
- ## 🧱 Structure
142
+ ## How the logins fit together
32
143
 
33
- packages/
34
- ├── auth/ # Contains all classes for handling login and sessions
35
- ├── constants/ # Constains AuthType and TestProfile
144
+ AD and DigiD both log in through the same Keycloak server (`authn.<env>.denhaag.nl`), but in two
145
+ separate realms:
146
+
147
+ | Login | Keycloak realm | Used for |
148
+ |---|---|---|
149
+ | AD | `zgw-ad` | The AD login in front of all apps on test and acc (`WITH_AD_SESSION`). |
150
+ | DigiD | `zgw-publiek` | The DigiD login of the klantportaal and Open Forms. |
151
+
152
+ Because the klantportaal and Open Forms share the `zgw-publiek` realm, a DigiD session from one app also
153
+ works for the other: a session created through Open Forms opens the klantportaal logged in, and with a
154
+ klantportaal session the "Inloggen met DigiD" link on an Open Forms form logs in without asking for
155
+ DigiD credentials again. A consumer can therefore create the session through one app and use it to
156
+ navigate to the other.
36
157
 
37
158
  ---
38
159
 
39
- ## Auth
160
+ ## Known limitations
161
+
162
+ - eHerkenning doesn't take `LoginOptions` yet: it always starts from `PORTAL_BASE_URL` with the
163
+ klantportaal buttons.
164
+ - `refreshSession` always opens `PORTAL_BASE_URL` to check the session, also for sessions of other
165
+ apps such as Open Forms. Because the DigiD session is shared (see above), an Open Forms session is
166
+ checked through the klantportaal.
167
+ - Session file names have a fixed pattern, `<browser>-<authType>-<ENV>-<username>.json`, in
168
+ `SESSIONS_DIR` (default `./sessions`); only the folder can be changed. The app is not part of the
169
+ name, so within one repository two apps that log in the same user use one session file. Because the
170
+ DigiD session is shared between the klantportaal and Open Forms, that session works for both.
40
171
 
41
- # api
172
+ ---
173
+
174
+ ## Project structure
42
175
 
43
- Has the authentication logic for api calls for nl-portal
176
+ ```
177
+ src/
178
+ ├── auth/
179
+ │ ├── api/ # getApiTokenFromSession: an API token from a UI session (nl-portal)
180
+ │ ├── loginhandlers/ # a LoginHandler per login type
181
+ │ ├── pages/ # the login pages (AD, DigiD, eHerkenning) and the login overzicht page
182
+ │ ├── utils/ # SessionFileHelper (session file names), maskedFill
183
+ │ ├── getLoginHandler.ts, getSessionHandler.ts, sessionHandler.ts
184
+ ├── constants/ # AuthType and TestProfile
185
+ tests/ # real-account tests, see below
186
+ ```
44
187
 
45
- # loginhandlers
188
+ ---
46
189
 
47
- Has all the login handlers that are needed for the nl-portal-playwright-libraries
48
- The interface LoginHandler is used by the implementation
190
+ ## Tests
49
191
 
50
- # pages
192
+ The tests log in for real, the way a consumer does: a `TestProfile` plus the app's login handler,
193
+ through `getSessionHandler` and `SessionManager` (new session, reuse, refresh).
51
194
 
52
- Has all the login pages and the login overview page
195
+ 1. Install the dependencies with `pnpm install` (or `npm install`, see the note below).
196
+ 2. Copy `.env.example` to `.env` and fill in the test users. What each user is and how to set it up is
197
+ described in `tests/data/testProfiles.ts`. `ENV` (`ACC` or `TEST`) picks the environment: the app
198
+ URLs for it are in `tests/data/environments.ts`. Set `PORTAL_BASE_URL`, `OPEN_FORMS_FORM_URL` or
199
+ `AD_LOGIN_TARGET_URL` in `.env` only to use other URLs.
200
+ 3. Run `pnpm test` or `npm test` (or `npx playwright test --project=sessions` for only the DigiD sessions).
53
201
 
54
- # utils
202
+ Variables set in the command take priority over `.env`, e.g. to run against test:
55
203
 
56
- Has the sessionFileHelper which takes care of the filename for each session
204
+ ```bash
205
+ ENV=TEST pnpm test # or: ENV=TEST npm test
206
+ ```
207
+
208
+ > **pnpm or npm:** this repo uses pnpm (`packageManager` in `package.json`, `pnpm-lock.yaml`), but npm
209
+ > works too. Note that npm ignores `pnpm-lock.yaml` and creates its own `package-lock.json`, so it may
210
+ > install other dependency versions than the ones locked. That `package-lock.json` is in `.gitignore`.
211
+
212
+ | File | What |
213
+ |---|---|
214
+ | `tests/data/testProfiles.ts` | Test data: the test users as `TestProfile`, and the `.env` data each one needs. |
215
+ | `tests/data/environments.ts` | Test data: the app URLs per environment (`ENV`). |
216
+ | `tests/data/apps.ts` | Test data: one login handler per app (AD via GZAC, klantportaal, Open Forms). |
217
+ | `tests/utils/sessions.ts` | Helpers: get, age or remove a session, open an app with a saved session. |
218
+ | `tests/utils/env.ts` | Read `.env` values, skip a test when they are missing. |
219
+ | `tests/ad.setup.ts` | The AD session every other test starts from. |
220
+ | `tests/digid.spec.ts` | DigiD sessions for klantportaal and Open Forms. |
221
+ | `tests/getLoginHandler.spec.ts` | Required options, without logging in. |
222
+
223
+ A test whose data is missing in `.env` is skipped with the names of the missing variables.
224
+
225
+ ---
57
226
 
58
227
  ## Publishing to npm
59
228
 
60
- 1 - npm version minor/major/patch (npm version minor) -> this will update the package json version
61
- 2 - npm pack --dry-run (just for checking if it is all okay)
62
- 3 - npm login (follow the login instructions)
63
- 4 - npm publish
229
+ 1. `pnpm version major|minor|patch` (or `npm version …`) updates the version in `package.json` (2.0 is a major).
230
+ 2. `pnpm pack --dry-run` (or `npm pack --dry-run`) shows what will be published.
231
+ 3. `npm login` (follow the instructions).
232
+ 4. `pnpm publish` (or `npm publish`). Both run the build first through `prepublishOnly`, which calls
233
+ `pnpm build`, so pnpm has to be installed either way.
@@ -1,9 +1,26 @@
1
1
  import { AuthType } from '../constants/authTypes';
2
2
  import { LoginHandler } from './loginHandler';
3
+ import { LoginOptions } from './pages/loginOverzichtPage';
3
4
  /**
5
+ * Shortcut for creating the login handler for an auth type. Creating the handler directly, e.g.
6
+ * `new DigidLoginHandler(options)`, checks at compile time that the required options are there;
7
+ * this function checks at runtime.
8
+ *
4
9
  * @param authType type of login
5
- * @param adTargetUrl URL to navigate to before logging in for the `ad-session` auth type (the
6
- * app behind the firewall), supplied by the consumer of this library. Required when
7
- * `authType` is `'ad-session'`, ignored otherwise.
10
+ * @param options where to start the login, supplied by the consumer of this library.
11
+ * - `ad-session`: `startUrl` is required - the app behind the firewall to navigate to before logging in.
12
+ * - `digid` / `digid_gemachtigde`: `loginButton` is required - the app's DigiD button. `startUrl` defaults
13
+ * to `PORTAL_BASE_URL`; `cookieButton` is optional.
14
+ * - other auth types: ignored.
15
+ *
16
+ * @example
17
+ * getLoginHandler('digid', {
18
+ * startUrl: 'https://openformulieren-zgw.acc.denhaag.nl/<form>/startpagina',
19
+ * loginButton: (page) => page.getByRole('link', { name: 'Inloggen met DigiD' }),
20
+ * cookieButton: (page) => page.locator('button[class*="cookie-notice__accept"]'),
21
+ * });
22
+ *
23
+ * @example
24
+ * getLoginHandler('ad-session', { startUrl: 'https://alg-zgw.test.denhaag.nl/' });
8
25
  */
9
- export declare function getLoginHandler(authType: AuthType, adTargetUrl?: string): LoginHandler;
26
+ export declare function getLoginHandler(authType: AuthType, options?: LoginOptions): LoginHandler;
@@ -1,8 +1,20 @@
1
+ import { LoginHandler } from './loginHandler';
1
2
  import { TestProfile } from '../constants';
2
3
  /**
3
- * @param testProfile
4
- * @param adTargetUrl URL to navigate to before logging in when `testProfile.authType` is
5
- * `'ad-session'` (the app behind the firewall), supplied by the consumer of this library.
6
- * Required in that case, ignored otherwise.
4
+ * @param testProfile the test user to log in
5
+ * @param loginHandler the login handler for the app the user logs in to, with that app's options, e.g.
6
+ * `new DigidLoginHandler({ loginButton, ... })` or `getLoginHandler(authType, options)`. Required for
7
+ * auth types that need options (`ad-session`, `digid`, `digid_gemachtigde`); left out, the handler
8
+ * for `testProfile.authType` is created without options.
9
+ *
10
+ * @example
11
+ * // once per app
12
+ * export const openFormsDigid = new DigidLoginHandler({
13
+ * startUrl: 'https://openformulieren-zgw.acc.denhaag.nl/<form>/startpagina',
14
+ * loginButton: (page) => page.getByRole('link', { name: 'Inloggen met DigiD' }),
15
+ * cookieButton: (page) => page.locator('button[class*="cookie-notice__accept"]'),
16
+ * });
17
+ *
18
+ * getSessionHandler(digidUser1, openFormsDigid);
7
19
  */
8
- export declare function getSessionHandler(testProfile: TestProfile, adTargetUrl?: string): import("nl-portal-playwright-libraries").SessionHandler;
20
+ export declare function getSessionHandler(testProfile: TestProfile, loginHandler?: LoginHandler): import("nl-portal-playwright-libraries").SessionHandler;
@@ -1,7 +1,16 @@
1
1
  import { Page } from '@playwright/test';
2
2
  import { Account } from 'nl-portal-playwright-libraries';
3
+ import { LoginOptionsWithButton } from '../pages/loginOverzichtPage';
3
4
  import { LoginHandler } from '../loginHandler';
4
5
  export declare class DigidGemachtigdeLoginHandler implements LoginHandler {
6
+ private readonly options;
7
+ /**
8
+ * Create one per app, so every test user that logs in to that app shares its options.
9
+ *
10
+ * @param options the app's DigiD machtigen login button (required), and optionally where to start and the
11
+ * app's cookie banner, supplied by the consumer of this library
12
+ */
13
+ constructor(options: LoginOptionsWithButton);
5
14
  /**
6
15
  * @param page the Playwright page to perform the login on
7
16
  * @param account login details, supplied by the consumer of this library
@@ -1,7 +1,16 @@
1
1
  import { Page } from '@playwright/test';
2
2
  import { Account } from 'nl-portal-playwright-libraries';
3
+ import { LoginOptionsWithButton } from '../pages/loginOverzichtPage';
3
4
  import { LoginHandler } from '../loginHandler';
4
5
  export declare class DigidLoginHandler implements LoginHandler {
6
+ private readonly options;
7
+ /**
8
+ * Create one per app, so every test user that logs in to that app shares its options.
9
+ *
10
+ * @param options the app's DigiD login button (required), and optionally where to start and the
11
+ * app's cookie banner, supplied by the consumer of this library
12
+ */
13
+ constructor(options: LoginOptionsWithButton);
5
14
  /**
6
15
  * @param page the Playwright page to perform the login on
7
16
  * @param account login details, supplied by the consumer of this library
@@ -1,14 +1,14 @@
1
1
  import { Locator, Page } from '@playwright/test';
2
2
  import { Account, BasePage } from 'nl-portal-playwright-libraries';
3
3
  export declare class ADLoginPage extends BasePage {
4
- gebruikersnaamInput: Locator;
5
- wachtwoordInput: Locator;
6
- volgendeInput: Locator;
7
- aanmeldenInput: Locator;
8
- kanAuthAppNietGebruikenLink: Locator;
9
- gebruikVerificatieCode: Locator;
4
+ usernameInput: Locator;
5
+ passwordInput: Locator;
6
+ nextInput: Locator;
7
+ signInInput: Locator;
8
+ cannotUseAuthAppLink: Locator;
9
+ useVerificationCode: Locator;
10
10
  codeInput: Locator;
11
- verifierenInput: Locator;
11
+ verifyInput: Locator;
12
12
  constructor(page: Page);
13
13
  openPage(path: string): Promise<void>;
14
14
  /**
@@ -1,21 +1,29 @@
1
- import { Page } from '@playwright/test';
2
- import { LoginOverzichtPage } from './loginOverzichtPage';
1
+ import { Locator, Page } from '@playwright/test';
2
+ import { LoginOptionsWithButton, LoginOverzichtPage } from './loginOverzichtPage';
3
3
  import { Account } from 'nl-portal-playwright-libraries';
4
4
  export declare class DigidLoginPage extends LoginOverzichtPage {
5
5
  constructor(page: Page);
6
6
  /**
7
7
  * @param account login details, supplied by the consumer of this library
8
8
  * @param fileName path of the storage state file to write the session to
9
+ * @param options the app's DigiD login button, and optionally where to start and its cookie
10
+ * banner, supplied by the consumer of this library
9
11
  */
10
- loginAndCreateNewSession(account: Account, fileName: string): Promise<void>;
12
+ loginAndCreateNewSession(account: Account, fileName: string, options: LoginOptionsWithButton): Promise<void>;
11
13
  /**
12
14
  * @param account login details, supplied by the consumer of this library
13
15
  * @param fileName path of the storage state file to write the session to
16
+ * @param options the app's DigiD machtigen login button, and optionally where to start and its cookie
17
+ * banner, supplied by the consumer of this library
14
18
  */
15
- loginAndCreateNewGemachtigdeSession(account: Account, fileName: string): Promise<void>;
19
+ loginAndCreateNewGemachtigdeSession(account: Account, fileName: string, options: LoginOptionsWithButton): Promise<void>;
16
20
  /**
17
- * Indien er al een AD sessie is maar voor de verkeerde omgeving
18
- * Je krijgt dan een speciaal scherm waar je moet bevestigen voordat je door kan
21
+ * Accepts the app's cookie banner when the consumer supplied one, so the consent is in the saved session.
22
+ */
23
+ private acceptCookiesForApp;
24
+ /**
25
+ * When there is already an AD session, but for another environment, a special screen asks to
26
+ * confirm the account before you can continue.
19
27
  */
20
28
  handleAnySpecialADLoginScreen(): Promise<void>;
21
29
  /**
@@ -23,5 +31,8 @@ export declare class DigidLoginPage extends LoginOverzichtPage {
23
31
  * @param gemachtigde whether to log in as an authorized representative (machtiging) instead of a regular user
24
32
  */
25
33
  loginWithDigid(account: Account, gemachtigde?: boolean): Promise<import("@playwright/test").Response>;
26
- loginAlsDigidGemachtigde(): Promise<void>;
34
+ /**
35
+ * @param loginButton button that starts the DigiD machtigen login, supplied by the consumer of this library
36
+ */
37
+ loginAsDigidGemachtigde(loginButton: Locator): Promise<void>;
27
38
  }
@@ -6,16 +6,16 @@ export declare class EHerkenningLoginPage extends LoginOverzichtPage {
6
6
  private readonly buttonConfirmIdentityProviderSelection;
7
7
  private readonly textfieldUsername;
8
8
  private readonly textfieldPassword;
9
- private readonly inloggenKnop;
10
- private readonly verderKnop;
11
- private readonly verderLink;
9
+ private readonly loginButton;
10
+ private readonly continueButton;
11
+ private readonly continueLink;
12
12
  private readonly inputBsn;
13
- private readonly buttonZoek;
13
+ private readonly searchButton;
14
14
  constructor(page: Page);
15
15
  /**
16
16
  * @param account login details, supplied by the consumer of this library
17
17
  */
18
- probeerInTeLoggenMetEHerkenning(account: Account): Promise<void>;
18
+ tryLoginWithEHerkenning(account: Account): Promise<void>;
19
19
  /**
20
20
  * @param fileName path of the storage state file to write the session to
21
21
  * @param account login details, supplied by the consumer of this library
@@ -38,5 +38,5 @@ export declare class EHerkenningLoginPage extends LoginOverzichtPage {
38
38
  * @param gemachtigde login details of the authorized representative (bewindvoerder), supplied by the consumer of this library
39
39
  * @param file optional path of the storage state file to write the session to
40
40
  */
41
- loginAlsProfessioneelBewindvoerder(gemachtigde: Account, file?: string): Promise<void>;
41
+ loginAsProfessionalBewindvoerder(gemachtigde: Account, file?: string): Promise<void>;
42
42
  }
@@ -1,4 +1,4 @@
1
1
  export { ADLoginPage } from './adLoginPage';
2
2
  export { DigidLoginPage } from './digidLoginPage';
3
3
  export { EHerkenningLoginPage } from './eHerkenningLoginPage';
4
- export { LoginOverzichtPage } from './loginOverzichtPage';
4
+ export { LoginOverzichtPage, type LoginOptionsWithButton, type LoginOptions } from './loginOverzichtPage';
@@ -1,16 +1,71 @@
1
1
  import { Locator, Page } from '@playwright/test';
2
2
  import { BasePage } from 'nl-portal-playwright-libraries';
3
+ /**
4
+ * Where and how to start the login, supplied by the consumer of this library. Applies to whichever
5
+ * auth type the login handler is created for; for `ad-session`, `startUrl` is the required app
6
+ * behind the firewall.
7
+ *
8
+ * @example
9
+ * // Klantportaal (starts from PORTAL_BASE_URL)
10
+ * getLoginHandler('digid', {
11
+ * loginButton: (page) => page.locator('#oidc-digid'),
12
+ * cookieButton: (page) => page.locator('#ppms_cm_agree-to-all'),
13
+ * });
14
+ *
15
+ * @example
16
+ * // Open Forms: start on the form and click its DigiD button
17
+ * getLoginHandler('digid', {
18
+ * startUrl: 'https://openformulieren-zgw.acc.denhaag.nl/<form>/startpagina',
19
+ * loginButton: (page) => page.getByRole('link', { name: 'Inloggen met DigiD' }),
20
+ * cookieButton: (page) => page.locator('button[class*="cookie-notice__accept"]'),
21
+ * });
22
+ */
23
+ export interface LoginOptions {
24
+ /**
25
+ * Returns the button that starts the login. A function because the page doesn't exist yet when
26
+ * the login handler is created. Required for DigiD; eHerkenning doesn't use these options yet.
27
+ */
28
+ loginButton?: (page: Page) => Locator;
29
+ /** URL of the page with the login button. Defaults to `PORTAL_BASE_URL`. */
30
+ startUrl?: string;
31
+ /**
32
+ * Returns the button that accepts the app's cookie banner after logging in, so the consent is
33
+ * saved in the session. Left out, no cookie banner is accepted.
34
+ */
35
+ cookieButton?: (page: Page) => Locator;
36
+ }
37
+ /** {@link LoginOptions} for logins that start from a button in the app (e.g. DigiD), so `loginButton` is required. */
38
+ export type LoginOptionsWithButton = LoginOptions & Required<Pick<LoginOptions, 'loginButton'>>;
3
39
  export declare class LoginOverzichtPage extends BasePage {
4
- digidLoginKnop: Locator;
5
- digidMachtigenLoginKnop: Locator;
6
- eHerkenningLoginKnop: Locator;
7
- eHerkenningMachtigingLoginKnop: Locator;
40
+ digidLoginButton: Locator;
41
+ digidMachtigenLoginButton: Locator;
42
+ eHerkenningLoginButton: Locator;
43
+ eHerkenningMachtigingLoginButton: Locator;
44
+ klantportaalCookieButton: Locator;
8
45
  constructor(page: Page);
9
- klikOpDigidLoginOptie(): Promise<void>;
10
- klikOpDigidMachtigenLoginOptie(): Promise<void>;
11
- klikOpEHerkenningLoginOptie(): Promise<void>;
12
- klikOpProfessioneelBewindvoerderLoginOptie(): Promise<void>;
13
- valideerDatHetLoginOverzichtZichtbaarIs(): Promise<void>;
14
- accepteerCookies(): Promise<void>;
46
+ /**
47
+ * Clicks the button that starts the login flow. Not every consumer has the login overzicht
48
+ * page (e.g. Open Forms), so the button to click can be supplied by the consumer.
49
+ *
50
+ * @param loginButton the button that starts the login flow
51
+ */
52
+ clickLoginButton(loginButton: Locator): Promise<void>;
53
+ clickDigidLoginOption(): Promise<void>;
54
+ clickDigidMachtigenLoginOption(): Promise<void>;
55
+ clickEHerkenningLoginOption(): Promise<void>;
56
+ clickProfessionalBewindvoerderLoginOption(): Promise<void>;
57
+ verifyLoginOverviewIsVisible(): Promise<void>;
58
+ /**
59
+ * Accepts the cookie banner and waits until the consent is stored in a cookie; skipped when the
60
+ * banner doesn't show within 10 seconds.
61
+ *
62
+ * @param cookieButton the button that accepts the cookie banner, defaults to the klantportaal banner
63
+ */
64
+ acceptCookies(cookieButton?: Locator): Promise<void>;
65
+ /**
66
+ * Waits until the cookies differ from `cookiesBefore` and have not changed for a second, at most 10 seconds.
67
+ */
68
+ private waitForCookiesToSettle;
69
+ private cookiesAsText;
15
70
  reloadPage(): Promise<void>;
16
71
  }