Skip to content

Commit 2a0fa56

Browse files
surishubhamsurishubham
authored
Merge pull request #2211 from RushilK7/stage
customCSS docs
2 parents 3167e27 + 1cd1098 commit 2a0fa56

File tree

2 files changed

+247
-0
lines changed

2 files changed

+247
-0
lines changed

‎docs/smartui-custom-css.md‎

Lines changed: 242 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,242 @@
1+
---
2+
id: smartui-custom-css
3+
title: SmartUI customCSS
4+
sidebar_label: customCSS
5+
description: Use customCSS to inject test-only CSS via SmartUI CLI using a file path or embedded string in smartui-web.json.
6+
slug: smartui-custom-css/
7+
keywords:
8+
- smartui
9+
- custom css
10+
- visual testing
11+
- cli
12+
- configuration
13+
- percy css
14+
---
15+
16+
<script type="application/ld+json"
17+
dangerouslySetInnerHTML={{ __html: JSON.stringify({
18+
"@context": "https://schema.org",
19+
"@type": "BreadcrumbList",
20+
"itemListElement": [{
21+
"@type": "ListItem",
22+
"position": 1,
23+
"name": "LambdaTest",
24+
"item": "https://www.lambdatest.com"
25+
},{
26+
"@type": "ListItem",
27+
"position": 2,
28+
"name": "Support",
29+
"item": "https://www.lambdatest.com/support/docs/"
30+
},{
31+
"@type": "ListItem",
32+
"position": 3,
33+
"name": "customCSS",
34+
"item": "https://www.lambdatest.com/support/docs/smartui-custom-css/"
35+
}]
36+
})
37+
}}
38+
></script>
39+
40+
## SmartUI customCSS
41+
42+
Use customCSS to apply test‑only styles at snapshot time without changing your app. It supports two input styles:
43+
44+
- File path (recommended for maintainability)
45+
- Embedded CSS string (quick and portable)
46+
47+
## Prerequisites
48+
- Node.js v20.3+ recommended
49+
- SmartUI CLI v4.1.40+ (exec and capture supported)
50+
- PROJECT_TOKEN
51+
52+
---
53+
54+
## Why customCSS Matters
55+
56+
1. **Stabilize Visual Diffs**: Hide or normalize volatile UI (ads, rotating banners, counters) to reduce false positives.
57+
2. **Environment Parity**: Enforce consistent fonts, themes, and spacing across different OS/browsers for predictable rendering.
58+
3. **Non‑Intrusive**: Avoid modifying application code or injecting styles in tests—keep visual adjustments in one place.
59+
60+
---
61+
62+
## 1) Configuration: Two Ways to Provide customCSS
63+
64+
A) File path method (recommended)
65+
- Put your CSS rules into a file (e.g., `code.css`) at the project root (or any path you prefer).
66+
- Reference that path in your SmartUI config.
67+
68+
```json
69+
{
70+
"web": { "browsers": ["chrome"], "viewports": [[1440, 900]] },
71+
"enableJavaScript": true,
72+
"customCSS": "./code.css"
73+
}
74+
```
75+
76+
B) Embedded string method (single‑line)
77+
- Provide the CSS directly as a JSON string. Use a single line (avoids path misdetection) and escape quotes if needed.
78+
79+
```json
80+
{
81+
"web": { "browsers": ["chrome"], "viewports": [[1440, 900]] },
82+
"enableJavaScript": true,
83+
"customCSS": "body{font-family:'Inter',sans-serif;} .banner,.ad{display:none!important;}"
84+
}
85+
```
86+
87+
Notes
88+
- Place customCSS only at the top level of your config (not inside web).
89+
- For multi‑line CSS in JSON, either:
90+
- keep it compact in one line, or
91+
- use the file‑path method to avoid escaping/formatting issues.
92+
- Paths in customCSS are relative to your project root.
93+
94+
---
95+
96+
## 2) Running with SmartUI (production)
97+
98+
Use either exec (wrap your test runner) or capture (static URLs). Ensure CLI is 4.1.40+.
99+
100+
Exec example (generic):
101+
```bash
102+
export PROJECT_TOKEN='YOUR_PROJECT_TOKEN'
103+
npx smartui --config smartui-web.json exec -- <your-test-command>
104+
```
105+
106+
Capture example (static URLs):
107+
```bash
108+
export PROJECT_TOKEN='YOUR_PROJECT_TOKEN'
109+
npx smartui capture --config smartui-web.json
110+
```
111+
112+
What you’ll see
113+
- CLI validates and injects your CSS at snapshot time
114+
- A CSS Injection Report in logs with the number of rules applied and any selectors with no matches
115+
116+
---
117+
118+
## Known Limitations
119+
120+
- Can be overridden by higher‑specificity inline styles; increase selector specificity if needed.
121+
122+
---
123+
124+
import Tabs from '@theme/Tabs';
125+
import TabItem from '@theme/TabItem';
126+
127+
## 3) Sample Use Cases
128+
129+
<Tabs>
130+
<TabItem value="stabilize" label="Stabilize Dynamic UI" default>
131+
132+
```css
133+
/* Hide elements that change between runs */
134+
.ad, .banner, #cookie-consent { display: none !important; }
135+
136+
/* Replace volatile text with a constant */
137+
[data-testid="rotating-copy"] { font-size: 0 !important; }
138+
[data-testid="rotating-copy"]::after { content: "Stable text for snapshots"; }
139+
```
140+
141+
</TabItem>
142+
<TabItem value="typography" label="Normalize Typography/Theme">
143+
144+
```css
145+
/* Force consistent light theme */
146+
:root { color-scheme: light; }
147+
body { font-family: "Inter", system-ui, sans-serif !important; color: #111827; background: #ffffff; }
148+
149+
/* Optional: Dark mode */
150+
/* :root { color-scheme: dark; }
151+
body { background: #0f172a !important; color: #e5e7eb !important; } */
152+
```
153+
154+
</TabItem>
155+
<TabItem value="layout" label="Layout Harmonization">
156+
157+
```css
158+
/* Center content and unify spacing (use carefully) */
159+
#root, main, section { display: flex !important; flex-direction: column !important; align-items: center !important; gap: 12px !important; }
160+
* { text-align: center !important; }
161+
```
162+
163+
</TabItem>
164+
<TabItem value="pii" label="Mask PII/Identifiers">
165+
166+
```css
167+
/* Hide IPs, locations, or IDs */
168+
#ip-value, #location-value { font-size: 0 !important; }
169+
#ip-value::after { content: "0.0.0.0" !important; }
170+
#location-value::after { content: "Unknown" !important; }
171+
```
172+
173+
</TabItem>
174+
<TabItem value="stress" label="Visual Stress Testing">
175+
176+
```css
177+
/* Deliberately apply a very different theme */
178+
body {
179+
font-family: "Century Gothic","URW Gothic","Apple Gothic",system-ui,Helvetica,Arial,sans-serif !important;
180+
background-image: linear-gradient(180deg,rgba(0,0,0,.55),rgba(0,0,0,.75)),
181+
url('https://images.unsplash.com/photo-1500530855697-b586d89ba3ee?q=80&w=1920&auto=format&fit=crop');
182+
background-size: cover; background-attachment: fixed; background-position: center;
183+
color: #e6e6e6 !important;
184+
}
185+
```
186+
187+
</TabItem>
188+
<TabItem value="flakiness" label="Reduce Flakiness">
189+
190+
```css
191+
/* Disable transitions/animations */
192+
*, *::before, *::after { transition: none !important; animation: none !important; }
193+
```
194+
195+
</TabItem>
196+
<TabItem value="brand" label="Mask Brand Cues">
197+
198+
```css
199+
/* Override brand cues (colors, shadows, shapes) */
200+
header, footer, nav { background: rgba(0,0,0,.45) !important; box-shadow: none !important; }
201+
.btn, a { border-radius: 10px !important; border: 1px solid rgba(255,255,255,.25) !important; }
202+
```
203+
204+
</TabItem>
205+
</Tabs>
206+
207+
---
208+
209+
## 4) Tips and Troubleshooting
210+
211+
- Prefer file path for larger stylesheets and team reviews.
212+
- For embedded strings, keep CSS single‑line or very carefully escaped (quotes, no raw newlines).
213+
- If a selector shows “no elements found” in the report, verify it exists at snapshot time or loosen/tighten the selector.
214+
- Keep CSS snapshot‑specific: target only what you need for stable and meaningful diffs.
215+
- If you need to wait for UI readiness, use SmartUI config waits:
216+
- `"waitForTimeout": 2000`
217+
- `"waitForPageRender": 5000`
218+
219+
---
220+
221+
## 5) Minimal templates
222+
223+
File path template:
224+
```json
225+
{
226+
"web": { "browsers": ["chrome"], "viewports": [[1440, 900]] },
227+
"enableJavaScript": true,
228+
"customCSS": "./path/to/visual.css"
229+
}
230+
```
231+
232+
Embedded string template:
233+
```json
234+
{
235+
"web": { "browsers": ["chrome"], "viewports": [[1440, 900]] },
236+
"enableJavaScript": true,
237+
"customCSS": "/* your CSS (single-line) */ body{font-family:'Inter',sans-serif;} .ad{display:none!important;}"
238+
}
239+
```
240+
241+
242+

‎sidebars.js‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3378,6 +3378,11 @@ module.exports = {
33783378
label: "Draw on UI",
33793379
id: "smartui-draw-on-ui",
33803380
},
3381+
{
3382+
type: "doc",
3383+
label: "customCSS",
3384+
id: "smartui-custom-css",
3385+
},
33813386
{
33823387
type: "category",
33833388
collapsed: true,

0 commit comments

Comments
 (0)