please-test 1.0.2

package/lib/index.d.ts

@@ -0,0 +1,37 @@
+import { Page, Locator } from '@playwright/test'
+
+export interface PageTarget {
+    url: string
+    title?: string
+}
+
+export default class Please {
+    constructor(page: Page)
+
+    // ── Locator ────────────────────────────────────────────────────────────────
+    detectLocator(selector: string): string
+    toLocator(selector: string): Locator
+
+    // ── Navigasi ───────────────────────────────────────────────────────────────
+    goto(target: PageTarget): Promise<void>
+    verifyPage(target: PageTarget): Promise<void>
+    url(): Promise<string>
+    title(): Promise<string>
+
+    // ── Tunggu & Interaksi ─────────────────────────────────────────────────────
+    untilShow(label: string, selector: string, timeout?: number): Promise<void>
+    wait(ms?: number): Promise<void>
+    click(label: string, selector: string, delay?: number): Promise<void>
+    fill(label: string, selector: string, value: string): Promise<void>
+    fillAndEnter(label: string, selector: string, value: string): Promise<void>
+    clear(label: string, selector: string): Promise<void>
+    scrollTo(label: string, selector: string): Promise<void>
+    uploadFile(label: string, selector: string, filePath: string): Promise<void>
+    datepicker(label: string, selector: string, value: string): Promise<void>
+
+    // ── Baca Nilai & Assert ────────────────────────────────────────────────────
+    see(label: string, selector: string, expected?: string, timeout?: number): Promise<string>
+
+    // ── Screenshot ─────────────────────────────────────────────────────────────
+    screenshot(label?: string): Promise<string>
+}

package/lib/index.js

@@ -0,0 +1,62 @@
+const { detectLocator, toLocator } = require('./locator')
+const { goto, verifyPage } = require('./navigation')
+const { untilShow, wait, click, fill, fillAndEnter, clear, scrollTo, uploadFile, datepicker } = require('./interaction')
+const { see } = require('./query')
+const { screenshot } = require('./screenshot')
+
+/** @typedef {{ url: string, title?: string }} PageInfo */
+
+class Please {
+    /**
+     * @param {import('@playwright/test').Page} page
+     * @param {import('@playwright/test').TestType<any,any>} [test]
+     */
+    constructor(page, test) {
+        this.page = page
+        this._step = test ? (name, fn) => test.step(name, fn) : (name, fn) => fn()
+    }
+
+    // ── Locator ────────────────────────────────────────────────────────────────
+    /** @param {string} selector */
+    detectLocator(selector)             { return detectLocator(selector) }
+    /** @param {string} selector */
+    toLocator(selector)                 { return toLocator(this.page, selector) }
+
+    // ── Navigasi ───────────────────────────────────────────────────────────────
+    /** @param {PageInfo} expected */
+    async goto(expected)                { return this._step(`Go to "${expected.url}"`, () => goto(this.page, expected)) }
+    /** @param {PageInfo} expected */
+    async verifyPage(expected)          { return this._step(`Verify page "${expected.url ?? expected.title}"`, () => verifyPage(this.page, expected)) }
+    async url()                         { return this.page.url() }
+    async title()                       { return this.page.title() }
+
+    // ── Tunggu & Interaksi ─────────────────────────────────────────────────────
+    /** @param {string} label @param {string} selector @param {number} [time] */
+    async untilShow(label, selector, time)              { return this._step(`Wait "${label}"`, () => untilShow(this.page, label, selector, time)) }
+    /** @param {number} [ms] */
+    async wait(ms)                                      { return wait(this.page, ms) }
+    /** @param {string} label @param {string} selector @param {number} [time] */
+    async click(label, selector, time)                  { return this._step(`Click "${label}"`, () => click(this.page, label, selector, time)) }
+    /** @param {string} label @param {string} selector @param {string} value */
+    async fill(label, selector, value)                  { return this._step(`Fill "${label}"`, () => fill(this.page, label, selector, value)) }
+    /** @param {string} label @param {string} selector @param {string} value */
+    async fillAndEnter(label, selector, value)          { return this._step(`Fill and enter "${label}"`, () => fillAndEnter(this.page, label, selector, value)) }
+    /** @param {string} label @param {string} selector */
+    async clear(label, selector)                        { return this._step(`Clear "${label}"`, () => clear(this.page, label, selector)) }
+    /** @param {string} label @param {string} selector */
+    async scrollTo(label, selector)                     { return this._step(`Scroll to "${label}"`, () => scrollTo(this.page, label, selector)) }
+    /** @param {string} label @param {string} selector @param {string} filePath */
+    async uploadFile(label, selector, filePath)         { return this._step(`Upload "${label}"`, () => uploadFile(this.page, label, selector, filePath)) }
+    /** @param {string} label @param {string} selector @param {string} value */
+    async datepicker(label, selector, value)            { return this._step(`Datepicker "${label}"`, () => datepicker(this.page, label, selector, value)) }
+
+    // ── Baca Nilai & Assert ────────────────────────────────────────────────────
+    /** @param {string} label @param {string} selector @param {string} [expected] @param {number} [time] */
+    async see(label, selector, expected, time)          { return this._step(`See "${label}"`, () => see(this.page, label, selector, expected, time)) }
+
+    // ── Screenshot ─────────────────────────────────────────────────────────────
+    /** @param {string} [label] */
+    async screenshot(label)                             { return screenshot(this.page, label) }
+}
+
+module.exports = Please

package/lib/interaction.js

@@ -0,0 +1,55 @@
+const { toLocator } = require('./locator')
+
+async function untilShow(page, label, selector, time = 20000) {
+    try {
+        await toLocator(page, selector).waitFor({ state: 'visible', timeout: time })
+    } catch {
+        const err = new Error(`"${label}" tidak muncul setelah ${time / 1000} detik`)
+        err.stack = err.message
+        throw err
+    }
+}
+
+async function wait(page, ms = 2000) {
+    await page.waitForTimeout(ms)
+}
+
+async function click(page, label, selector, time = undefined) {
+    if (time !== undefined) await wait(page, time)
+    await untilShow(page, label, selector)
+    await toLocator(page, selector).scrollIntoViewIfNeeded()
+    await toLocator(page, selector).click()
+}
+
+async function fill(page, label, selector, value) {
+    await untilShow(page, label, selector)
+    await toLocator(page, selector).fill(value)
+}
+
+async function fillAndEnter(page, label, selector, value) {
+    await untilShow(page, label, selector)
+    const el = toLocator(page, selector)
+    await el.fill(value)
+    await el.press('Enter')
+}
+
+async function clear(page, label, selector) {
+    await untilShow(page, label, selector)
+    await toLocator(page, selector).clear()
+}
+
+async function scrollTo(page, label, selector) {
+    await untilShow(page, label, selector)
+    await toLocator(page, selector).scrollIntoViewIfNeeded()
+}
+
+async function uploadFile(page, label, selector, filePath) {
+    await untilShow(page, label, selector)
+    await toLocator(page, selector).setInputFiles(filePath)
+}
+
+async function datepicker(page, label, selector, value) {
+    await fillAndEnter(page, label, selector, value)
+}
+
+module.exports = { untilShow, wait, click, fill, fillAndEnter, clear, scrollTo, uploadFile, datepicker }

package/lib/locator.js

@@ -0,0 +1,50 @@
+const ARIA_ROLES = new Set([
+    'alert', 'alertdialog', 'application', 'article', 'banner', 'blockquote',
+    'button', 'caption', 'cell', 'checkbox', 'code', 'columnheader', 'combobox',
+    'complementary', 'contentinfo', 'definition', 'deletion', 'dialog', 'directory',
+    'document', 'emphasis', 'feed', 'figure', 'form', 'generic', 'grid', 'gridcell',
+    'group', 'heading', 'img', 'insertion', 'link', 'list', 'listbox', 'listitem',
+    'log', 'main', 'marquee', 'math', 'menu', 'menubar', 'menuitem', 'menuitemcheckbox',
+    'menuitemradio', 'meter', 'navigation', 'none', 'note', 'option', 'paragraph',
+    'presentation', 'progressbar', 'radio', 'radiogroup', 'region', 'row', 'rowgroup',
+    'rowheader', 'scrollbar', 'search', 'searchbox', 'separator', 'slider', 'spinbutton',
+    'status', 'strong', 'subscript', 'superscript', 'switch', 'tab', 'table', 'tablist',
+    'tabpanel', 'term', 'textbox', 'timer', 'toolbar', 'tooltip', 'tree', 'treegrid',
+    'treeitem',
+])
+
+function detectLocator(selector) {
+    if (selector.startsWith('//') || selector.startsWith('(//'))
+        return `xpath=${selector}`
+    if (selector.startsWith('#'))
+        return selector
+    if (selector.startsWith('.') || selector.startsWith('[') || /[\s>:+~]/.test(selector) || /[.#\[:]/.test(selector))
+        return selector
+    if (/^(a|abbr|address|article|aside|audio|b|blockquote|body|br|button|canvas|caption|cite|code|col|colgroup|data|datalist|dd|del|details|dfn|dialog|div|dl|dt|em|embed|fieldset|figcaption|figure|footer|form|h1|h2|h3|h4|h5|h6|head|header|hr|html|i|iframe|img|input|ins|kbd|label|legend|li|link|main|map|mark|menu|meta|meter|nav|noscript|object|ol|optgroup|option|output|p|picture|pre|progress|q|rp|rt|ruby|s|samp|script|section|select|small|source|span|strong|style|sub|summary|sup|table|tbody|td|template|textarea|tfoot|th|thead|time|title|tr|track|u|ul|var|video|wbr)$/.test(selector))
+        return selector
+    throw new Error(`Selector "${selector}" tidak dapat dikenali. Gunakan: #id, .class, tag, xpath (//), CSS, text=, label=, placeholder=, alt=, title=, testid=, atau shorthand button=Name.`)
+}
+
+function toLocator(page, selector) {
+    const eq = selector.indexOf('=')
+    if (eq !== -1) {
+        const prefix = selector.slice(0, eq)
+        const value = selector.slice(eq + 1)
+        if (prefix === 'role') {
+            const nameMatch = value.match(/^(\w+)\[name=(.+)\]$/)
+            return nameMatch
+                ? page.getByRole(nameMatch[1], { name: nameMatch[2] })
+                : page.getByRole(value)
+        }
+        if (ARIA_ROLES.has(prefix))   return page.getByRole(prefix, { name: value })
+        if (prefix === 'label')       return page.getByLabel(value)
+        if (prefix === 'text')        return page.getByText(value)
+        if (prefix === 'placeholder') return page.getByPlaceholder(value)
+        if (prefix === 'alt')         return page.getByAltText(value)
+        if (prefix === 'title')       return page.getByTitle(value)
+        if (prefix === 'testid')      return page.getByTestId(value)
+    }
+    return page.locator(detectLocator(selector))
+}
+
+module.exports = { detectLocator, toLocator }

package/lib/navigation.js

@@ -0,0 +1,24 @@
+async function goto(page, { url, title }) {
+    await page.goto(url)
+    if (title) {
+        const actual = await page.title()
+        if (actual !== title)
+            throw new Error(`Title tidak sesuai. Expected: "${title}", actual: "${actual}"`)
+    }
+}
+
+async function verifyPage(page, { url, title }) {
+    await page.waitForLoadState('domcontentloaded')
+    if (url) {
+        const actual = page.url()
+        if (!actual.includes(url))
+            throw new Error(`URL tidak sesuai. Expected mengandung: "${url}", actual: "${actual}"`)
+    }
+    if (title) {
+        const actual = await page.title()
+        if (actual !== title)
+            throw new Error(`Title tidak sesuai. Expected: "${title}", actual: "${actual}"`)
+    }
+}
+
+module.exports = { goto, verifyPage }

package/lib/query.js

@@ -0,0 +1,17 @@
+const { toLocator } = require('./locator')
+const { untilShow, wait } = require('./interaction')
+
+async function see(page, label, selector, expected = undefined, time = undefined) {
+    await untilShow(page, label, selector)
+    if (time !== undefined) await wait(page, time)
+    const el = toLocator(page, selector)
+    const tag = await el.evaluate(node => node.tagName.toLowerCase())
+    const actual = ['input', 'textarea', 'select'].includes(tag)
+        ? await el.inputValue()
+        : await el.innerText()
+    if (expected !== undefined && actual !== expected)
+        throw new Error(`[${label}] konten tidak sesuai\n  Expected: "${expected}"\n  Received: "${actual}"`)
+    return actual
+}
+
+module.exports = { see }

package/lib/screenshot.js

@@ -0,0 +1,16 @@
+const path = require('path')
+const fs = require('fs')
+
+async function screenshot(page, label) {
+    const dir = path.resolve('screenshots')
+    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true })
+    const datetime = new Date().toISOString().replace(/[:.]/g, '-')
+    const slug = label
+        ? `${label.replace(/[^a-zA-Z0-9_-]/g, '_')}_${datetime}`
+        : datetime
+    const filePath = path.join(dir, `${slug}.png`)
+    await page.screenshot({ path: filePath })
+    return filePath
+}
+
+module.exports = { screenshot }

package/package.json

@@ -0,0 +1,49 @@
+{
+    "name": "please-test",
+    "version": "1.0.2",
+    "description": "Shorthand helper for @playwright/test — expressive locators, readable error messages",
+    "main": "lib/index.js",
+    "types": "lib/index.d.ts",
+    "scripts": {
+        "test:unit": "node test/unit.test.js && node test/screenshot.test.js",
+        "test:login": "playwright test test/login.spec.js",
+        "test:types": "tsd",
+        "test": "playwright test test/smoke.test.js"
+    },
+    "tsd": {
+        "entrypoint": "lib/index.d.ts"
+    },
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/ghany-ersa/please-test.git"
+    },
+    "keywords": [
+        "playwright",
+        "automation",
+        "testing",
+        "e2e",
+        "shorthand"
+    ],
+    "author": "ghany-ersa <ghanyersa24@gmail.com>",
+    "license": "MIT",
+    "peerDependencies": {
+        "@playwright/test": ">=1.0.0"
+    },
+    "engines": {
+        "node": ">=14.0.0"
+    },
+    "files": [
+        "lib/index.js",
+        "lib/index.d.ts",
+        "lib/interaction.js",
+        "lib/locator.js",
+        "lib/navigation.js",
+        "lib/query.js",
+        "lib/screenshot.js"
+    ],
+    "devDependencies": {
+        "@playwright/test": "^1.61.0",
+        "tsd": "^0.33.0",
+        "typescript": "^6.0.3"
+    }
+}

package/readme.md

@@ -0,0 +1,103 @@
+# please-test
+
+Shorthand helper untuk `@playwright/test` — locator ekspresif dan pesan error yang deskriptif.
+
+`page` datang dari fixture `@playwright/test`, please-test hanya menyediakan shorthand di atasnya.
+
+---
+
+## Instalasi
+
+Pastikan Node.js >= 14 sudah terinstall.
+
+```bash
+npm install please-test @playwright/test && npx playwright install
+```
+
+```js
+const { test } = require('@playwright/test')
+const Please = require('please-test')
+
+test('login berhasil', async ({ page }) => {
+    const please = new Please(page)
+
+    await please.goto({ url: 'https://myapp.com/login' })
+    await please.fill('Username', '#username', 'student')
+    await please.fill('Password', '#password', 'secret')
+    await please.click('Tombol Login', 'button=Login')
+    await please.see('Pesan Sukses', 'h1', 'Dashboard')
+})
+```
+
+---
+
+## API
+
+`please` adalah instance dari `new Please(page)`.
+
+### Navigasi
+
+| Method | Deskripsi |
+|---|---|
+| `goto({ url, title? })` | Navigasi ke URL; jika `title` diberikan, validasi title halaman |
+| `verifyPage({ url?, title? })` | Verifikasi URL dan/atau title halaman saat ini |
+| `url()` | Ambil URL halaman saat ini |
+| `title()` | Ambil title halaman saat ini |
+
+### Interaksi
+
+| Method | Deskripsi |
+|---|---|
+| `click(label, selector, time?)` | Klik elemen; `time` (ms) menunda klik setelah jeda |
+| `fill(label, selector, value)` | Isi input field |
+| `fillAndEnter(label, selector, value)` | Isi input dan tekan Enter |
+| `clear(label, selector)` | Kosongkan input field |
+| `scrollTo(label, selector)` | Scroll ke elemen |
+| `uploadFile(label, selector, path)` | Upload file via `input[type=file]` |
+| `datepicker(label, selector, value)` | Isi input datepicker |
+
+### Baca & Assert
+
+| Method | Deskripsi |
+|---|---|
+| `see(label, selector, expected?, time?)` | Baca konten elemen. Jika `expected` diberikan, throw jika tidak cocok — tetap mengembalikan nilai aktual |
+
+`see` otomatis membaca `value` untuk `input`/`textarea`/`select`, dan `innerText` untuk elemen lain.
+
+### Tunggu
+
+| Method | Deskripsi |
+|---|---|
+| `untilShow(label, selector, time?)` | Tunggu elemen muncul (default 20 detik) |
+| `wait(ms?)` | Jeda eksplisit (default 2000ms) |
+
+### Screenshot
+
+| Method | Deskripsi |
+|---|---|
+| `screenshot(label?)` | Simpan screenshot ke `screenshots/label_datetime.png` |
+
+---
+
+## Selector
+
+Semua method yang menerima `selector` otomatis mendeteksi tipe locator:
+
+| Format | Contoh |
+|---|---|
+| `#id` | `#username` |
+| `text=` | `text=Klik di sini` |
+| `role=` | `role=button[name=Submit]` |
+| `label=` | `label=Email` |
+| `role=Name` (shorthand) | `button=Login`, `link=Masuk`, `checkbox=Setuju` |
+| CSS selector | `.btn-primary`, `[data-id="x"]` |
+| XPath | `//button[@type="submit"]` |
+| Tag HTML | `h1`, `textarea` |
+
+> Shorthand `role=Name` didukung untuk semua ARIA role yang valid di Playwright: `button=Login`, `link=Masuk`, `checkbox=Setuju`, `textbox=Email`, `combobox=Negara`, dst.
+
+---
+
+## Lisensi
+
+MIT