Skip to content

Commit fe42386

Browse files
Copilotdaohoangson
Copilot
and
daohoangson
committed
Add comprehensive GitHub Copilot instructions
Co-authored-by: daohoangson <[email protected]>
1 parent 8eedc2a commit fe42386

File tree

2 files changed

+315
-0
lines changed

2 files changed

+315
-0
lines changed

‎.github/copilot-instructions.md‎

Lines changed: 134 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,134 @@
1+
# Flutter Widget from HTML
2+
3+
Flutter Widget from HTML is a monorepo containing Flutter/Dart packages that render HTML as Flutter widgets. The repository includes a core package, enhanced wrapper, feature extensions, and a demo app for testing.
4+
5+
Always reference these instructions first and fallback to search or bash commands only when you encounter unexpected information that does not match the info here.
6+
7+
## Working Effectively
8+
9+
Bootstrap, build, and test the repository:
10+
- Check Flutter installation: `flutter --version` -- should show Flutter 3.35.2+ and Dart 3.9.0+
11+
- Install dependencies: `./tool/pub-get.sh` -- takes 30 seconds. Dependencies are installed across all packages.
12+
- Run full analysis and tests: `./tool/test.sh` -- takes 3-4 minutes. NEVER CANCEL. Set timeout to 10+ minutes.
13+
- Run tests with coverage: `./tool/test.sh --coverage` -- takes 2-3 minutes. NEVER CANCEL. Set timeout to 8+ minutes.
14+
- Format code: `dart format . --output none` -- takes 2-3 seconds.
15+
16+
## Build Commands
17+
18+
Web demo app:
19+
- Build for web: `cd demo_app && flutter build web --release` -- takes 45 seconds. NEVER CANCEL. Set timeout to 2+ minutes.
20+
- Run web app: `cd demo_app && flutter run -d web-server --web-port 8080 --web-hostname 0.0.0.0` -- starts development server.
21+
22+
Android demo app:
23+
- Build debug APK: `cd demo_app && flutter build apk --debug` -- takes 1-2 minutes. NEVER CANCEL. Set timeout to 5+ minutes.
24+
- Build release APKs: `cd demo_app && flutter build apk --release --split-per-abi` -- takes 2-3 minutes. NEVER CANCEL. Set timeout to 8+ minutes.
25+
26+
## Testing and Validation
27+
28+
Run tests with different options:
29+
- Run all tests: `./tool/test.sh` -- takes 3-4 minutes. Runs analysis and tests for all packages.
30+
- Run with coverage: `./tool/test.sh --coverage` -- takes 2-3 minutes. Generates coverage reports.
31+
- Update golden files: `./tool/test.sh --update-goldens` -- takes 2-3 minutes. Updates visual regression test images.
32+
- Update goldens only: `./tool/update-goldens.sh` -- convenience script for updating golden files.
33+
34+
Individual package testing:
35+
- Analyze specific package: `cd packages/core && flutter analyze` -- takes 1-2 seconds.
36+
- Test specific package: `cd packages/core && flutter test` -- takes 40-45 seconds.
37+
- Test enhanced package: `cd packages/enhanced && flutter test` -- takes 20-25 seconds.
38+
39+
Integration testing:
40+
- Web integration tests require chromedriver running on port 4444.
41+
- Start chromedriver: `chromedriver --port=4444 &` then set `CHROMEDRIVER_PORT_4444=yes`.
42+
43+
## Validation Scenarios
44+
45+
Always test these scenarios after making changes:
46+
- **Basic HTML rendering**: Run `cd demo_app && flutter test` to verify golden file tests pass -- takes 5-10 seconds.
47+
- **Web demo functionality**: Build and run the demo app with `cd demo_app && flutter build web && flutter run -d web-server` and verify HTML rendering works.
48+
- **Core package functionality**: Run `cd packages/core && flutter test` to ensure core widget functionality works.
49+
- **Enhanced package features**: Run `cd packages/enhanced && flutter test` to verify enhanced features work.
50+
- **Code formatting**: Run `dart format . --output none` and ensure no files are changed.
51+
52+
## Repository Structure
53+
54+
Key directories and their purposes:
55+
- `packages/core/`: Core HTML widget package (`flutter_widget_from_html_core`)
56+
- `packages/enhanced/`: Enhanced wrapper package (`flutter_widget_from_html`)
57+
- `packages/fwfh_*/`: Feature extension packages (cached images, webview, audio, etc.)
58+
- `demo_app/`: Example Flutter app for manual testing and screenshots
59+
- `tool/`: Helper scripts for dependency management, testing, and publishing
60+
- `test/images/`: Golden file assets for visual regression testing
61+
62+
## Package Dependencies
63+
64+
SDK requirements:
65+
- Flutter: >=3.32.0
66+
- Dart: >=3.4.0
67+
68+
Main dependencies across packages:
69+
- `csslib`: CSS parsing
70+
- `html`: HTML parsing
71+
- `logging`: Logging framework
72+
- `flutter_test`, `test`, `golden_toolkit`: Testing frameworks
73+
74+
## Common Tasks
75+
76+
Check for outdated dependencies:
77+
- `./tool/pub-outdated.sh` -- shows outdated packages across all modules.
78+
79+
Publish packages to pub.dev:
80+
- `./tool/pub-publish.sh` -- publishes all packages. Requires clean git state and version bumps.
81+
82+
Update demo app platform files:
83+
- `./tool/update-demo_app-files.sh` -- regenerates iOS, Android, macOS, and web platform files.
84+
85+
## Development Workflow
86+
87+
When making changes:
88+
1. Run `./tool/pub-get.sh` to ensure all dependencies are current
89+
2. Make your changes to the appropriate package(s)
90+
3. Format code with `dart format .`
91+
4. Run relevant tests: `./tool/test.sh` or individual package tests
92+
5. For UI changes, verify golden files with `./tool/test.sh --update-goldens`
93+
6. Build and test the demo app to verify changes work end-to-end
94+
95+
## Key Files
96+
97+
Configuration files:
98+
- `analysis_options.yaml`: Linting rules in each package directory
99+
- `pubspec.yaml`: Package configuration in each package directory
100+
- `dart_test.yaml`: Test configuration in demo_app
101+
102+
Important scripts:
103+
- `tool/test.sh`: Main test runner with analysis and testing
104+
- `tool/pub-get.sh`: Dependency installation across all packages
105+
- `tool/update-goldens.sh`: Golden file update helper
106+
107+
## Known Issues and Workarounds
108+
109+
Format checking in CI:
110+
- `dart format --set-exit-if-changed` is commented out in CI due to GitHub Actions issues
111+
- Always run `dart format .` locally before committing
112+
113+
Web integration tests:
114+
- Require Chrome/chromedriver for JavaScript interop testing
115+
- Only run when `CHROMEDRIVER_PORT_4444` environment variable is set
116+
117+
Golden file testing:
118+
- Visual regression tests use `golden_toolkit` framework
119+
- Golden files stored in `test/images/` directories
120+
- Regenerate with `--update-goldens` flag when making UI changes
121+
122+
## Timeout Guidelines
123+
124+
**CRITICAL**: Always use appropriate timeouts and NEVER CANCEL long-running commands:
125+
126+
- Dependency installation (`./tool/pub-get.sh`): 30 seconds -- use 2+ minute timeout
127+
- Full test suite (`./tool/test.sh`): 3-4 minutes -- use 10+ minute timeout, NEVER CANCEL
128+
- Coverage tests (`./tool/test.sh --coverage`): 2-3 minutes -- use 8+ minute timeout, NEVER CANCEL
129+
- Golden updates (`./tool/test.sh --update-goldens`): 2-3 minutes -- use 8+ minute timeout, NEVER CANCEL
130+
- Web build (`flutter build web`): 45 seconds -- use 2+ minute timeout, NEVER CANCEL
131+
- APK builds (`flutter build apk`): 1-3 minutes -- use 5-8+ minute timeout, NEVER CANCEL
132+
- Individual package tests: 20-45 seconds -- use 2+ minute timeout
133+
134+
Build and test commands may take longer than expected. This is NORMAL. Always wait for completion.

‎demo_app/coverage/lcov.info‎

Lines changed: 181 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,181 @@
1+
SF:lib/screens/smilie.dart
2+
DA:12,1
3+
DA:14,1
4+
DA:15,1
5+
DA:16,1
6+
DA:19,1
7+
DA:21,1
8+
DA:23,2
9+
DA:32,1
10+
DA:33,3
11+
DA:34,2
12+
DA:38,1
13+
DA:40,1
14+
DA:41,2
15+
DA:42,2
16+
DA:43,2
17+
DA:44,2
18+
DA:48,1
19+
LF:17
20+
LH:17
21+
end_of_record
22+
SF:lib/screens/golden.dart
23+
DA:17,1
24+
DA:19,1
25+
DA:21,1
26+
DA:22,3
27+
DA:24,1
28+
DA:26,1
29+
DA:28,2
30+
DA:31,2
31+
DA:32,1
32+
DA:34,1
33+
DA:36,3
34+
DA:38,1
35+
DA:40,1
36+
DA:41,1
37+
DA:48,2
38+
DA:50,1
39+
DA:52,3
40+
DA:54,1
41+
DA:56,2
42+
DA:61,1
43+
DA:62,1
44+
DA:63,2
45+
DA:70,1
46+
DA:71,1
47+
DA:72,1
48+
DA:73,1
49+
DA:75,1
50+
DA:77,1
51+
DA:91,0
52+
DA:93,0
53+
DA:94,0
54+
DA:103,0
55+
DA:105,0
56+
DA:107,0
57+
DA:109,0
58+
DA:111,0
59+
DA:112,0
60+
DA:113,0
61+
DA:114,0
62+
DA:115,0
63+
DA:116,0
64+
DA:117,0
65+
DA:118,0
66+
DA:127,0
67+
DA:129,0
68+
DA:130,0
69+
DA:133,0
70+
DA:134,0
71+
DA:135,0
72+
DA:136,0
73+
DA:137,0
74+
DA:138,0
75+
DA:139,0
76+
DA:140,0
77+
DA:141,0
78+
DA:142,0
79+
DA:146,0
80+
DA:147,0
81+
DA:148,0
82+
DA:149,0
83+
DA:150,0
84+
DA:154,0
85+
DA:155,0
86+
DA:156,0
87+
DA:161,0
88+
DA:162,0
89+
DA:163,0
90+
DA:164,0
91+
DA:165,0
92+
DA:167,0
93+
DA:169,0
94+
DA:170,0
95+
DA:171,0
96+
DA:178,0
97+
DA:179,0
98+
DA:180,0
99+
DA:181,0
100+
DA:187,0
101+
DA:189,0
102+
DA:190,0
103+
DA:191,0
104+
DA:192,0
105+
DA:196,0
106+
DA:197,0
107+
DA:198,0
108+
DA:199,0
109+
DA:200,0
110+
DA:201,0
111+
DA:205,0
112+
LF:89
113+
LH:28
114+
end_of_record
115+
SF:lib/widgets/popup_menu.dart
116+
DA:6,4
117+
DA:8,0
118+
DA:10,0
119+
DA:12,0
120+
DA:14,2
121+
DA:22,1
122+
DA:29,1
123+
DA:31,1
124+
DA:32,0
125+
DA:33,0
126+
DA:34,0
127+
DA:37,0
128+
DA:38,0
129+
DA:39,0
130+
DA:40,0
131+
DA:41,0
132+
DA:43,0
133+
DA:44,0
134+
DA:47,0
135+
DA:48,0
136+
DA:49,0
137+
DA:51,0
138+
DA:52,0
139+
DA:53,0
140+
DA:57,0
141+
DA:58,0
142+
DA:60,0
143+
DA:62,0
144+
DA:65,0
145+
DA:66,0
146+
DA:68,0
147+
DA:70,0
148+
DA:83,1
149+
DA:89,1
150+
DA:91,1
151+
DA:92,2
152+
DA:93,1
153+
DA:94,1
154+
DA:97,2
155+
DA:106,0
156+
DA:111,0
157+
DA:113,0
158+
DA:114,0
159+
DA:115,0
160+
DA:116,0
161+
DA:117,0
162+
DA:129,1
163+
DA:133,1
164+
DA:135,0
165+
DA:138,0
166+
DA:139,0
167+
DA:141,0
168+
LF:52
169+
LH:14
170+
end_of_record
171+
SF:lib/widgets/selection_area.dart
172+
DA:8,1
173+
DA:14,1
174+
DA:16,1
175+
DA:17,1
176+
DA:18,1
177+
DA:21,1
178+
DA:22,0
179+
LF:7
180+
LH:6
181+
end_of_record

0 commit comments

Comments
 (0)