You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Custom CSS injection is a specialized feature in SmartUI that allows you to apply test-only styles during snapshot capture without modifying your application code. This feature enables you to stabilize visual tests by normalizing dynamic content, enforcing consistent styling across environments, and masking sensitive information—all while keeping your visual testing logic centralized and maintainable.
41
50
42
-
Use customCSS to apply test‑only styles at snapshot time without changing your app. It supports two input styles:
51
+
### Why Custom CSS Matters
43
52
44
-
- File path (recommended for maintainability)
45
-
- Embedded CSS string (quick and portable)
53
+
1.**Stabilize Visual Diffs**: Hide or normalize volatile UI elements (ads, rotating banners, dynamic counters, time-based content) to reduce false positives in your visual regression tests.
54
+
55
+
2.**Environment Parity**: Enforce consistent fonts, themes, and spacing across different operating systems, browsers, and devices for predictable rendering and accurate comparisons.
56
+
57
+
3.**Non-Intrusive Testing**: Avoid modifying application code or injecting styles directly in test scripts. Keep all visual adjustments in a centralized configuration, making it easier to maintain and review.
58
+
59
+
4.**Enhanced Test Reliability**: Reduce test flakiness by masking dynamic elements that change between test runs, ensuring your visual tests focus on meaningful UI changes rather than transient content.
46
60
47
61
## Prerequisites
48
-
- Node.js v20.3+ recommended
49
-
- SmartUI CLI v4.1.40+ (exec and capture supported)
50
-
- PROJECT_TOKEN
62
+
63
+
Before using the Custom CSS feature, ensure you meet the following requirements:
64
+
65
+
- Node.js v20.3+ (recommended)
66
+
- SmartUI CLI v4.1.40+ (supports both `exec` and `capture` commands)
67
+
- Valid PROJECT_TOKEN configured in your environment
51
68
52
69
---
53
70
54
-
## Why customCSS Matters
71
+
#Custom CSS Configuration in SmartUI
55
72
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.
73
+
SmartUI supports two methods for providing custom CSS: file path (recommended for maintainability) and embedded string (quick and portable). Choose the method that best fits your workflow.
59
74
60
-
---
75
+
## Method 1: File Path (Recommended)
61
76
62
-
## 1) Configuration: Two Ways to Provide customCSS
77
+
The file path method is recommended for larger stylesheets and team collaboration. Create a separate CSS file in your project and reference it in your SmartUI configuration.
63
78
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.
79
+
**Steps:**
67
80
68
-
```json
81
+
1. Create a CSS file (e.g., `visual-test-styles.css` or `code.css`) in your project directory.
82
+
83
+
2. Add your CSS rules to the file:
84
+
85
+
```css title="visual-test-styles.css"
86
+
/* General samples: pick what suits your use case */
87
+
88
+
/* 1) Normalize fonts for consistent rendering */
89
+
body { font-family: system-ui, -apple-system, Segoe UI, Roboto, sans-serif; }
90
+
91
+
/* 2) Hide flaky, time-based banners or rotating promos */
- 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.
132
+
## Configuration Guidelines
93
133
94
-
---
134
+
-**Placement**: The `customCSS` property must be placed at the top level of your configuration file (not inside the `web` object). Placing it inside `web` will result in a "must NOT have additional properties" error.
95
135
96
-
## 2) Running with SmartUI (production)
136
+
-**Path Resolution**: File paths are relative to your project root directory. Ensure the CSS file exists at the specified path. Files outside the project directory may not be accessible.
97
137
98
-
Use either exec (wrap your test runner) or capture (static URLs). Ensure CLI is 4.1.40+.
138
+
-**CSS Specificity**: Your custom CSS will be injected at snapshot time. Use `!important` declarations if you need to override existing styles. If CSS is overridden by inline styles, increase selector specificity (e.g., `.target-class` → `#specific-id .target-class`).
-**Multi-line CSS**: For multi-line CSS, prefer the file path method to avoid JSON escaping complexity. If using embedded strings, keep rules compact and single-line.
105
141
106
-
Capture example (static URLs):
107
-
```bash
108
-
export PROJECT_TOKEN='YOUR_PROJECT_TOKEN'
109
-
npx smartui capture --config smartui-web.json
110
-
```
142
+
-**Method Selection**: Choose the file path method for larger stylesheets and team collaboration. Use embedded strings only for quick, single-use CSS rules.
143
+
144
+
-**CSS Organization**: Keep your CSS snapshot-specific—target only elements that need stabilization or normalization. Avoid broad selectors that might affect unintended elements.
145
+
146
+
-**JSON Escaping**: When using embedded strings, escape quotes properly:
147
+
- Use single quotes within CSS strings: `"body{font-family:'Inter',sans-serif;}"`
148
+
- Or escape double quotes: `"body{font-family:\"Inter\",sans-serif;}"`
111
149
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
150
+
-**Selector Verification**: If the CSS Injection Report shows "no elements found" or "invalid selector" errors:
151
+
- Verify the element exists at snapshot time (use browser dev tools)
152
+
- Check selector specificity—it may need to be more specific or less specific
153
+
- Consider timing issues—ensure the element is rendered before snapshot capture
154
+
- Check the CSS Injection Report in logs for detailed feedback
155
+
156
+
-**CLI Version**: Ensure SmartUI CLI v4.1.40+ is installed. You can verify this by running `npx smartui --version`. Older versions may not support the `customCSS` feature.
157
+
158
+
-**Waiting for UI Readiness**: If you need to wait for UI elements to be ready before snapshots, add these options to your configuration:
159
+
```json
160
+
{
161
+
"waitForTimeout": 2000,
162
+
"waitForPageRender": 5000,
163
+
"customCSS": "./visual-test-styles.css"
164
+
}
165
+
```
115
166
116
167
---
117
168
169
+
118
170
## Known Limitations
119
171
120
-
- Can be overridden by higher‑specificity inline styles; increase selector specificity if needed.
172
+
The Custom CSS feature has the following limitations:
173
+
174
+
-**Specificity Constraints**: Custom CSS can be overridden by higher-specificity inline styles. Increase your selector specificity or use `!important` declarations if needed.
175
+
176
+
-**Snapshot-Only Application**: CSS is only injected during snapshot capture and does not affect your application's runtime behavior.
177
+
178
+
-**File Path Resolution**: Ensure CSS file paths are correctly specified relative to your project root. Files outside the project directory may not be accessible.
121
179
122
180
---
123
181
124
-
import Tabs from '@theme/Tabs';
125
-
import TabItem from '@theme/TabItem';
182
+
## Use Cases for Custom CSS
126
183
127
-
## 3) Sample Use Cases
184
+
The custom CSS feature is particularly valuable in the following scenarios:
0 commit comments