proxymail-qa 0.5.1 → 0.7.0

package/README.md

@@ -106,6 +106,34 @@ await qa.setPassword(address, { password: 'the-new-test-password' });
 const result = await qa.checkEmail(address, { type: 'link', expectHost: 'staging.example.com' });
 expect(result.failed).toEqual([]);
 
+// A localised email: in German, with the user's name in it.
+await qa.checkEmail(address, { expectLanguage: 'de', expectText: ['Hallo Maya'] });
+
+// What to type or pick in each field of a sign-up form, from a new address
+// made for it: a username and password that fit the rules, the date of birth
+// in the field's format, a country the drop-down offers. You fill it in.
+const { values } = await qa.formValues({
+  fields: [
+    { id: 'email', type: 'email', label: 'Email' },
+    { id: 'dob', type: 'text', label: 'Date of birth', placeholder: 'DD/MM/YYYY' },
+  ],
+});
+
+// Borrow an account in the state the test needs. Your hooks make one when
+// none is free, confirm its state and put it back; they talk to your app,
+// Proxy Mail QA never does.
+await qa.withAccount(
+  {
+    tags: ['verified', 'premium'],
+    create: async (account) => signUpAndUpgrade(account.address, account.password),
+    check: async (account) => (await getUser(account.address)).plan === 'premium',
+    reset: async (account) => resetUser(account.address),
+  },
+  async (account) => {
+    // …the test…
+  },
+);
+
 // A run: this client's calls add what they saw, for a report on the pull
 // request. In GitHub Actions, the Proxy Mail QA action does this for you and
 // the client picks the run up from PROXYMAIL_QA_RUN.

package/dist/index.d.ts

@@ -23,6 +23,62 @@ export interface Address {
     has_password: boolean;
     email_count: number;
     latest: Omit<Match, 'address' | 'email_id' | 'service_domain'> | null;
+    checked_out_until?: string;
+}
+export interface CheckoutOptions extends Omit<ListAddressesOptions, 'limit' | 'before'> {
+    minutes?: number;
+}
+export interface CheckedOutAccount extends Address {
+    checkout: {
+        token: string;
+        until: string;
+    };
+}
+export interface FormFieldInput {
+    id?: string;
+    type?: string;
+    name?: string;
+    label?: string;
+    placeholder?: string;
+    autocomplete?: string;
+    group?: string;
+    pattern?: string;
+    minLength?: number;
+    maxLength?: number;
+    options?: Array<{
+        value: string;
+        label?: string;
+    }>;
+}
+export interface FormValuesOptions extends Omit<CreateAddressInput, 'password' | 'persona' | 'name'> {
+    fields: FormFieldInput[];
+    address?: string;
+}
+export interface FormValue {
+    id: string;
+    kind: 'email' | 'confirm_email' | 'first_name' | 'last_name' | 'full_name' | 'username' | 'password' | 'confirm_password' | 'date_of_birth' | 'birth_day' | 'birth_month' | 'birth_year' | 'country' | 'other';
+    value: string | null;
+    note?: string;
+}
+export interface FormValues {
+    address: string;
+    created: boolean;
+    persona: Persona | null;
+    password?: string;
+    values: FormValue[];
+}
+export interface PreparedAccountOptions extends CheckoutOptions {
+    create?: (account: CheckedOutAccount & {
+        password: string;
+    }) => Promise<void>;
+    newAccount?: Omit<CreateAddressInput, 'password'>;
+    check?: (account: CheckedOutAccount) => Promise<boolean | void>;
+    reset?: (account: CheckedOutAccount) => Promise<void>;
+    attempts?: number;
+}
+export interface ReturnState {
+    addTags?: string[];
+    removeTags?: string[];
 }
 export interface CreatedAddress extends Address {
     password?: string;
@@ -134,7 +190,7 @@ export interface CountOptions {
     subtype?: CountSubtype | CountSubtype[];
 }
 export type CountSubtype = 'otp' | 'coupon' | 'verify' | 'magic_signin' | 'invite' | 'reset' | 'other' | 'any';
-export type CheckId = 'spf' | 'dkim' | 'dmarc' | 'local_links' | 'plain_http' | 'expected_host' | 'expiry' | 'plain_text' | 'size' | 'images_only';
+export type CheckId = 'spf' | 'dkim' | 'dmarc' | 'local_links' | 'plain_http' | 'expected_host' | 'expiry' | 'plain_text' | 'size' | 'images_only' | 'expected_text' | 'language';
 export interface EmailCheck {
     check: CheckId;
     status: 'pass' | 'fail' | 'warn' | 'skip';
@@ -158,6 +214,8 @@ export interface EmailChecks {
 export interface CheckOptions extends CountOptions {
     emailId?: string;
     expectHost?: string;
+    expectText?: string[];
+    expectLanguage?: string;
 }
 export interface NoEmail {
     address: string;
@@ -215,8 +273,24 @@ export declare class ProxyMailQA {
         password: true;
     }): Promise<CreatedAddressWithPassword>;
     createAddress(input?: CreateAddressInput): Promise<CreatedAddress>;
+    formValues(options: FormValuesOptions): Promise<FormValues>;
     listAddresses(options?: ListAddressesOptions): Promise<Address[]>;
     getAddress(address: string): Promise<Address>;
+    checkOutAccount(options?: CheckoutOptions): Promise<CheckedOutAccount>;
+    extendCheckout(account: CheckedOutAccount, minutes?: number): Promise<{
+        address: string;
+        checkout: {
+            token: string;
+            until: string;
+        };
+    }>;
+    returnAccount(account: CheckedOutAccount, state?: ReturnState): Promise<Address>;
+    withAccount<T>(options: PreparedAccountOptions, fn: (account: CheckedOutAccount) => Promise<T>): Promise<T>;
+    private prepareAccount;
+    private newAccount;
+    private failedCheck;
+    private restoreAccount;
+    private note;
     updateAddress(address: string, patch: AddressPatch): Promise<Address>;
     deleteAddress(address: string): Promise<void>;
     waitForCode(address: string, options?: WaitOptions): Promise<Match>;

package/dist/index.js

@@ -90,6 +90,33 @@ export class ProxyMailQA {
             country: input.country,
         });
     }
+    // What to type or pick in each field of a sign-up form, from a new address
+    // made for it (a date of birth if it asks, a country it offers, a password
+    // that fits its rules) or one made earlier (address). You fill it in.
+    formValues(options) {
+        return this.request('POST', '/form-values', {
+            fields: options.fields.map((f) => ({
+                id: f.id,
+                type: f.type,
+                name: f.name,
+                label: f.label,
+                placeholder: f.placeholder,
+                autocomplete: f.autocomplete,
+                group: f.group,
+                pattern: f.pattern,
+                min_length: f.minLength,
+                max_length: f.maxLength,
+                options: f.options,
+            })),
+            address: options.address,
+            label: options.label,
+            lifetime_days: options.lifetimeDays,
+            domain: options.domain,
+            age: options.age,
+            date_of_birth: options.dateOfBirth,
+            country: options.country,
+        });
+    }
     // Newest first. With filters, finds test accounts made earlier, such as
     // an under-18 in GB with a saved password: every filter given must match.
     listAddresses(options = {}) {
@@ -115,6 +142,173 @@ export class ProxyMailQA {
     getAddress(address) {
         return this.request('GET', `/addresses/${encodeURIComponent(address)}`);
     }
+    // Checks out an account matching every filter that nobody else holds, the
+    // least recently used first, for `minutes` (default 10). Throws
+    // ProxyMailQAError 409 when every match is checked out, 404 when none
+    // match. Tag accounts with their state (verified, premium…) to make pools.
+    checkOutAccount(options = {}) {
+        return this.request('POST', '/addresses/checkout', {
+            tags: options.tags,
+            country: options.country,
+            min_age: options.minAge,
+            max_age: options.maxAge,
+            has_password: options.hasPassword,
+            search: options.search,
+            minutes: options.minutes,
+        });
+    }
+    // More time from now (default 10 minutes).
+    extendCheckout(account, minutes) {
+        return this.request('POST', `/addresses/${encodeURIComponent(account.address)}/extend`, {
+            token: account.checkout.token,
+            minutes,
+        });
+    }
+    // Frees it for the next test, recording any change to its state.
+    returnAccount(account, state = {}) {
+        return this.request('POST', `/addresses/${encodeURIComponent(account.address)}/return`, {
+            token: account.checkout.token,
+            add_tags: state.addTags,
+            remove_tags: state.removeTags,
+        });
+    }
+    // Checks out an account, runs fn with it, and always returns it. fn can
+    // say what state it left the account in by returning { addTags, removeTags }.
+    // With create, check and reset (PreparedAccountOptions), the account is
+    // also confirmed to be in the state the test needs, a new one is made when
+    // none is free, and its state is restored afterwards.
+    async withAccount(options, fn) {
+        const account = await this.prepareAccount(options);
+        let state = {};
+        let result;
+        try {
+            result = await fn(account);
+            if (result && typeof result === 'object' && ('addTags' in result || 'removeTags' in result))
+                state = result;
+        }
+        catch (err) {
+            await this.restoreAccount(account, options, state).catch(() => { });
+            throw err;
+        }
+        await this.restoreAccount(account, options, state);
+        return result;
+    }
+    // A checked-out account in the state the test needs, or an error saying why
+    // there isn't one.
+    async prepareAccount(options) {
+        const { create, check, reset, newAccount, attempts = 3, ...filters } = options;
+        const tried = [];
+        let lastProblem = '';
+        for (let i = 0; i < attempts; i++) {
+            let account;
+            try {
+                account = await this.checkOutAccount(filters);
+            }
+            catch (err) {
+                if (!(err instanceof ProxyMailQAError && (err.status === 404 || err.status === 409)))
+                    throw err;
+                // None matches, or every match is busy: make one, if the test can.
+                if (create)
+                    return this.newAccount(options);
+                // Accounts that failed their check have left the pool.
+                if (tried.length)
+                    break;
+                throw err;
+            }
+            // The pool has come round again: every match has been tried.
+            if (tried.includes(account.address)) {
+                await this.returnAccount(account).catch(() => { });
+                break;
+            }
+            tried.push(account.address);
+            let problem = await this.failedCheck(check, account);
+            if (problem === null)
+                return account;
+            if (reset) {
+                problem = await reset(account).then(() => this.failedCheck(check, account), (err) => `reset failed: ${message(err)}`);
+                if (problem === null)
+                    return account;
+            }
+            lastProblem = problem;
+            await this.note(`Test account failed its check (${problem}); it loses its tags and is tagged check-failed.`, account.address);
+            await this.returnAccount(account, { addTags: ['check-failed'], removeTags: filters.tags }).catch(() => { });
+        }
+        if (create)
+            return this.newAccount(options);
+        throw new Error(tried.length
+            ? `No test account passed the check: tried ${tried.join(', ')}${lastProblem ? ` (last: ${lastProblem})` : ''}. Pass create to make one.`
+            : 'No test account passed the check. Pass create to make one.');
+    }
+    // Makes an account with the test's create hook, holding it from the start
+    // so no parallel test takes it half made, then tags and checks it.
+    async newAccount(options) {
+        const { create, check, newAccount = {}, tags = [], country, minAge, maxAge, minutes } = options;
+        if (!create)
+            throw new Error('Pass create to make new accounts.');
+        if ((minAge !== undefined || maxAge !== undefined) && !newAccount.age && !newAccount.dateOfBirth) {
+            throw new Error('Give newAccount an age or dateOfBirth, so new accounts match minAge and maxAge.');
+        }
+        const created = await this.createAddress({ ...newAccount, country: newAccount.country ?? country, password: true });
+        const held = await this.checkOutAccount({ search: created.address, minutes });
+        if (held.address !== created.address) {
+            await this.returnAccount(held).catch(() => { });
+            throw new Error(`Couldn't hold the new account ${created.address}.`);
+        }
+        try {
+            await create({ ...held, password: created.password });
+            const tagged = await this.updateAddress(created.address, { tags: [...new Set([...held.tags, ...tags.map((t) => t.toLowerCase())])] });
+            const account = { ...tagged, checkout: held.checkout };
+            const ages = age(account.persona?.date_of_birth);
+            if (ages !== null && ((minAge !== undefined && ages < minAge) || (maxAge !== undefined && ages > maxAge))) {
+                throw new Error(`The new account is ${ages}, outside minAge and maxAge: give newAccount a matching age.`);
+            }
+            const problem = await this.failedCheck(check, account);
+            if (problem !== null)
+                throw new Error(`The new account ${created.address} failed its check after create: ${problem}`);
+            await this.note(`Made a new test account${tags.length ? ` tagged ${tags.join(', ')}` : ''}.`, created.address);
+            return account;
+        }
+        catch (err) {
+            // Untagged, it stays out of the pool; it expires with its address.
+            await this.updateAddress(created.address, { tags: held.tags }).catch(() => { });
+            await this.returnAccount(held).catch(() => { });
+            throw err;
+        }
+    }
+    // null when the account passes (or there's no check), or why it doesn't.
+    async failedCheck(check, account) {
+        if (!check)
+            return null;
+        try {
+            return (await check(account)) === false ? 'check returned false' : null;
+        }
+        catch (err) {
+            return message(err);
+        }
+    }
+    // Runs reset, then returns the account. If reset fails, the account leaves
+    // the pool's state (needs-reset) and the error is thrown.
+    async restoreAccount(account, options, state) {
+        if (options.reset) {
+            try {
+                await options.reset(account);
+            }
+            catch (err) {
+                await this.note(`Couldn't reset the test account (${message(err)}); it loses its tags and is tagged needs-reset.`, account.address);
+                await this.returnAccount(account, {
+                    addTags: [...(state.addTags ?? []), 'needs-reset'],
+                    removeTags: [...(state.removeTags ?? []), ...(options.tags ?? [])],
+                }).catch(() => { });
+                throw err;
+            }
+        }
+        await this.returnAccount(account, state).catch(() => { });
+    }
+    // Adds a line to the current run, if there is one, without failing the test.
+    async note(text, address) {
+        if (this.run)
+            await this.addRunNote(text, { address }).catch(() => { });
+    }
     updateAddress(address, patch) {
         return this.request('PATCH', `/addresses/${encodeURIComponent(address)}`, patch);
     }
@@ -154,15 +348,21 @@ export class ProxyMailQA {
     }
     // Checks one email the address received: SPF, DKIM and DMARC, links to
     // localhost or plain http, where its link goes (expectHost), a stated
-    // expiry, a plain-text part, size and image-only emails. Doesn't wait: wait
-    // for the email first. Throws ProxyMailQAError (404) when none matches.
+    // expiry, a plain-text part, size and image-only emails, and given phrases
+    // (expectText) and its language (expectLanguage). Doesn't wait: wait for
+    // the email first. Throws ProxyMailQAError (404) when none matches.
     checkEmail(address, options = {}) {
         const extra = {};
         if (options.emailId)
             extra.email_id = options.emailId;
         if (options.expectHost)
             extra.expect_host = options.expectHost;
-        return this.request('GET', `/addresses/${encodeURIComponent(address)}/checks${countQuery(options, extra)}`);
+        if (options.expectLanguage)
+            extra.expect_language = options.expectLanguage;
+        let query = countQuery(options, extra);
+        for (const phrase of options.expectText ?? [])
+            query += `${query ? '&' : '?'}expect_text=${encodeURIComponent(phrase)}`;
+        return this.request('GET', `/addresses/${encodeURIComponent(address)}/checks${query}`);
     }
     // Resolves when no matching email arrives within timeout seconds (default
     // 30; longer repeats the request), for checks such as "an unsubscribed user
@@ -268,3 +468,12 @@ export class ProxyMailQA {
         }
     }
 }
+const message = (err) => (err instanceof Error ? err.message : String(err));
+// Whole years from a YYYY-MM-DD date of birth, or null without one.
+function age(dateOfBirth) {
+    if (!dateOfBirth)
+        return null;
+    const [y, m, d] = dateOfBirth.split('-').map(Number);
+    const now = new Date();
+    return now.getUTCFullYear() - y - (now.getUTCMonth() + 1 < m || (now.getUTCMonth() + 1 === m && now.getUTCDate() < d) ? 1 : 0);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "proxymail-qa",
-  "version": "0.5.1",
+  "version": "0.7.0",
   "description": "Disposable test inboxes for Playwright, Cypress and scripts: create an address, then wait for its verification code or link.",
   "license": "MIT",
   "author": "Proxy Mail QA <hello@proxymail.qa> (https://proxymail.qa)",