e2e-testid 1.0.3

package/README.md

@@ -0,0 +1,166 @@
+Here is a clean, professional `README.md` you can use for your package:
+
+---
+
+# e2e-testid
+
+A lightweight utility for generating stable and consistent `data-testid` values for E2E testing.
+
+It helps teams standardize selectors, avoid flaky tests, and create namespaced test IDs in a clean and scalable way.
+
+---
+
+## ✨ Why e2e-testid?
+
+E2E tests often break because:
+
+* Selectors are inconsistent
+* Developers rename classes
+* IDs are not standardized
+* There is no naming convention
+
+`e2e-testid` solves this by providing:
+
+* Consistent `data-testid` naming
+* Namespacing support (`Auth.Login.Submit`)
+* Automatic test id builder per feature
+* Optional runtime toggle (enable only in E2E builds)
+
+---
+
+## 📦 Installation
+
+```bash
+npm install e2e-testid
+```
+
+or
+
+```bash
+yarn add e2e-testid
+```
+
+---
+
+## 🚀 Basic Usage
+
+```js
+const { tid } = require("e2e-testid");
+
+<button {...tid("Auth.Login.Submit")}>
+  Login
+</button>
+```
+
+Output:
+
+```html
+<button data-testid="Auth.Login.Submit">
+  Login
+</button>
+```
+
+---
+
+## 🏗 Namespaced Builder
+
+Create a namespace for a feature:
+
+```js
+const { createTid } = require("e2e-testid");
+
+const t = createTid("Auth.Login");
+
+<button {...t.tid("Submit")}>
+  Login
+</button>
+```
+
+Result:
+
+```html
+<button data-testid="Auth.Login.Submit">
+```
+
+---
+
+## 🔁 Child Namespaces
+
+```js
+const auth = createTid("Auth");
+const login = auth.child("Login");
+
+login.tid("Submit");
+```
+
+Generates:
+
+```
+Auth.Login.Submit
+```
+
+---
+
+## ⚙️ Enable / Disable Test IDs
+
+You can enable test IDs only in E2E environments:
+
+```js
+const { configure } = require("e2e-testid");
+
+configure({ enabled: true });
+```
+
+Or automatically enable using environment variable:
+
+```bash
+E2E=true
+```
+
+This prevents `data-testid` from being included in production builds if desired.
+
+---
+
+## 🧠 Recommended Naming Convention
+
+Use structured names:
+
+```
+Feature.Screen.Element
+```
+
+Examples:
+
+```
+Auth.Login.EmailInput
+Auth.Login.Submit
+Cart.Checkout.Total
+Checkout.Success.Message
+```
+
+This keeps your test suite readable and scalable.
+
+---
+
+## 🎯 Works With
+
+* Playwright
+* Cypress
+* Selenium
+* Any E2E framework
+
+---
+
+## 📌 Example With Playwright
+
+```js
+await page.getByTestId("Auth.Login.Submit").click();
+```
+
+---
+
+## 📄 License
+
+ISC
+
+

package/index.js

@@ -0,0 +1,126 @@
+const state = {
+  enabled: (() => {
+    const v =
+      (typeof process !== "undefined" &&
+        process.env &&
+        (process.env.E2E_TESTIDS || process.env.E2E || process.env.NODE_ENV)) ||
+      "";
+    const s = String(v).toLowerCase();
+    if (s === "1" || s === "true" || s === "yes" || s === "on") return true;
+    if (s === "test" || s === "e2e") return true;
+    return false;
+  })(),
+  attr: "data-testid",
+  sep: ".",
+  sanitizer: (x) =>
+    String(x)
+      .trim()
+      .replace(/\s+/g, "_")
+      .replace(/[^\w.\-:/]/g, "_")
+      .replace(/_+/g, "_")
+      .replace(/^_+|_+$/g, "")
+};
+
+function configure(options = {}) {
+  if (Object.prototype.hasOwnProperty.call(options, "enabled")) {
+    state.enabled = Boolean(options.enabled);
+  }
+  if (Object.prototype.hasOwnProperty.call(options, "attr") && options.attr) {
+    state.attr = String(options.attr);
+  }
+  if (Object.prototype.hasOwnProperty.call(options, "sep") && options.sep) {
+    state.sep = String(options.sep);
+  }
+  if (
+    Object.prototype.hasOwnProperty.call(options, "sanitizer") &&
+    typeof options.sanitizer === "function"
+  ) {
+    state.sanitizer = options.sanitizer;
+  }
+  return getConfig();
+}
+
+function getConfig() {
+  return { enabled: state.enabled, attr: state.attr, sep: state.sep };
+}
+
+function isEnabled() {
+  return state.enabled;
+}
+
+function normalizePart(part) {
+  if (part === null || part === undefined) return "";
+  const s = state.sanitizer(part);
+  return s;
+}
+
+function joinParts(parts) {
+  const out = [];
+  for (const p of parts) {
+    const n = normalizePart(p);
+    if (n) out.push(n);
+  }
+  return out.join(state.sep);
+}
+
+function ensureId(idOrParts) {
+  if (Array.isArray(idOrParts)) return joinParts(idOrParts);
+  return normalizePart(idOrParts);
+}
+
+function tid(id, extraProps) {
+  const props = extraProps && typeof extraProps === "object" ? extraProps : {};
+  if (!state.enabled) return props;
+  const testId = ensureId(id);
+  if (!testId) return props;
+  return { ...props, [state.attr]: testId };
+}
+
+function tidValue(id) {
+  const testId = ensureId(id);
+  return testId;
+}
+
+function createTid(namespace) {
+  const base = normalizePart(namespace);
+  const builder = (...parts) => joinParts([base, ...parts]);
+
+  builder.base = () => base;
+
+  builder.of = (...parts) => joinParts([base, ...parts]);
+
+  builder.tid = (...parts) => tid(joinParts([base, ...parts]));
+
+  builder.value = (...parts) => tidValue(joinParts([base, ...parts]));
+
+  builder.with = (parts, extraProps) =>
+    tid(
+      joinParts([base, ...(Array.isArray(parts) ? parts : [parts])]),
+      extraProps
+    );
+
+  builder.child = (childNamespace) => createTid(joinParts([base, childNamespace]));
+
+  builder.enable = () => configure({ enabled: true });
+
+  builder.disable = () => configure({ enabled: false });
+
+  return builder;
+}
+
+function makeJourneyTid(feature, screen) {
+  const f = normalizePart(feature);
+  const s = normalizePart(screen);
+  const t = createTid(joinParts([f, s]));
+  return t;
+}
+
+module.exports = {
+  configure,
+  getConfig,
+  isEnabled,
+  tid,
+  tidValue,
+  createTid,
+  makeJourneyTid
+};

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "e2e-testid",
+  "version": "1.0.3",
+  "description": "A small utility for stable and consistent data-testid generation for E2E testing.",
+  "license": "ISC",
+  "author": "Taha Kourani",
+  "type": "commonjs",
+  "main": "index.js",
+  "exports": {
+    ".": "./index.js"
+  },
+  "keywords": [
+    "e2e",
+    "testing",
+    "testid",
+    "data-testid",
+    "playwright",
+    "cypress",
+    "selectors",
+    "react"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TechTaha-lab/react-packages.git"
+  },
+  "bugs": {
+    "url": "https://github.com/TechTaha-lab/react-packages/issues"
+  },
+  "homepage": "https://github.com/TechTaha-lab/react-packages#readme",
+  "files": [
+    "index.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=14"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "echo \"No tests yet\" && exit 0"
+  }
+}