diff --git a/engine/src/flutter/README.md b/engine/src/flutter/README.md index 48592480d1..f11da0bb0e 100644 --- a/engine/src/flutter/README.md +++ b/engine/src/flutter/README.md @@ -1,12 +1,5 @@ # Flutter Engine -[![Flutter CI Status](https://flutter-dashboard.appspot.com/api/public/build-status-badge?repo=engine)](https://flutter-dashboard.appspot.com/#/build?repo=engine) - -Flutter is Google's SDK for crafting beautiful, fast user experiences for -mobile, web, and desktop from a single codebase. Flutter works with existing -code, is used by developers and organizations around the world, and is free -and open source. - The Flutter Engine is a portable runtime for hosting [Flutter](https://flutter.dev) applications. It implements Flutter's core libraries, including animation and graphics, file and network I/O, @@ -15,16 +8,11 @@ toolchain. Most developers will interact with Flutter via the [Flutter Framework](https://github.com/flutter/flutter), which provides a modern, reactive framework, and a rich set of platform, layout and foundation widgets. -If you want to run/contribute to Flutter Web engine, more tooling can be -found at [felt](lib/web_ui/README.md#using-felt). -This is a tool written to make web engine development experience easy. +More tooling is available to make development experiences easier: -If you are new to Flutter, then you will find more general information -on the Flutter project, including tutorials and samples, on our Web -site at [Flutter.dev](https://flutter.dev). For specific information -about Flutter's APIs, consider our API reference which can be found at -the [docs.flutter.dev](https://docs.flutter.dev/). +| Target | Tool | +| ----------------- | ----------------------------------------------- | +| Web | [`felt`](lib/web_ui/README.md#using-felt) | +| Mobile or Desktop | [`et`](tools/engine_tool/README.md#engine-tool) | -Flutter is a fully open source project, and we welcome contributions. -Information on how to get started can be found at our -[contributor guide](CONTRIBUTING.md). +To learn about running tests, see [testing the engine](docs/testing/Testing-the-engine.md). diff --git a/engine/src/flutter/docs/testing/Testing-the-engine.md b/engine/src/flutter/docs/testing/Testing-the-engine.md index 67304aa68d..b6695891b8 100644 --- a/engine/src/flutter/docs/testing/Testing-the-engine.md +++ b/engine/src/flutter/docs/testing/Testing-the-engine.md @@ -1,16 +1,13 @@ -## Testing the engine - -Pull requests submitted to the [engine repository](https://github.com/flutter/engine) -should be tested to prevent functional regressions. +# Testing the engine This guide describes how to write and run various types of tests in the engine. ## C++ - core engine -If you edit `.cc` files in https://github.com/flutter/engine/tree/main, +If you edit `.cc` files in [`engine`](../../), you're working on the core, portable Flutter engine. -### Unit tests +### Unit tests (C++) C++ unit tests are co-located with their header and source files. For instance, `fml/file.h` and `fml/file.cc` have a `fml/file_unittest.cc` in the same @@ -25,7 +22,7 @@ folder. You can run the C++ unit tests with: -``` +```sh testing/run_tests.py --type=engine ``` @@ -33,7 +30,7 @@ from the `flutter` directory, after building the engine variant to test (by default `host_debug_unopt`). To use a different variant (e.g. if you use an Apple Silicon Mac), run: -``` +```sh testing/run_tests.py --type=engine --variant=host_debug_unopt_arm64 ``` @@ -57,7 +54,7 @@ mocks for all other dependencies. ## Java - Android embedding -If you edit `.java` files in the https://github.com/flutter/engine/tree/main/shell/platform/android +If you edit `.java` files in the [`shell/platform/android`](../../shell/platform/android/) directory, you're working on the Android embedding which connects the core C++ engine to the Android SDK APIs and runtime. @@ -65,9 +62,9 @@ engine to the Android SDK APIs and runtime. For testing logic within a class at a unit level, create or add to a JUnit test. -Existing Java unit tests are located at https://github.com/flutter/engine/tree/main/shell/platform/android/test -and follow the Java package directory structure. Files in the `shell/platform/android/io/flutter/` -package tree can have a parallel file in the `shell/platform/android/test/io/flutter/` +Existing Java unit tests are located at [`shell/platform/android/test`](../../shell/platform/android/test) +and follow the Java package directory structure. Files in the [`shell/platform/android/io/flutter/`](../../shell/platform/android/io/flutter/) +package tree can have a parallel file in the [`shell/platform/android/test/io/flutter/`](../../shell/platform/android/test/io/flutter/) package tree. Files in matching directories are considered [package visible](https://docs.oracle.com/javase/tutorial/java/javaOO/accesscontrol.html) as is the case in standard Java. @@ -75,7 +72,7 @@ When editing production files in `shell/platform/android/io/flutter/`, the easiest step to add tests is to look for a matching `...Test.java` file in `shell/platform/android/test/io/flutter/`. -See the [Java unit test README](https://github.com/flutter/engine/blob/main/shell/platform/android/test/README.md) +See the [Java unit test README](../../shell/platform/android/test/README.md) for details. The engine repo has a unified build system to build C, C++, Objective-C, @@ -87,7 +84,7 @@ standard Android project. Instead, the engine provides the script: -``` +```sh testing/run_tests.py --type=java ``` @@ -159,7 +156,7 @@ in the root of the monorepo. See ## Objective-C - iOS embedding -If you edit `.h` or `.mm` files in the https://github.com/flutter/engine/tree/main/shell/platform/darwin/ios +If you edit `.h` or `.mm` files in the [`shell/platform/darwin/ios`](../../shell/platform/darwin/ios) directory, you're working on the iOS embedding which connects the core C++ engine to the iOS SDK APIs and runtime. @@ -168,23 +165,22 @@ engine to the iOS SDK APIs and runtime. For testing logic within a class in isolation, create or add to a XCTestCase. The iOS unit testing infrastructure is split in 2 different locations. The -`...Test.mm` files in https://github.com/flutter/engine/tree/main/shell/platform/darwin/ios -contain the unit tests themselves. The -https://github.com/flutter/engine/tree/main/testing/ios/IosUnitTests directory -contains an Xcode container project to execute the test. +`...Test.mm` files in [`shell/platform/darwin/ios`](../../shell/platform/darwin/ios) +contain the unit tests themselves. The [`testing/ios/IosUnitTests`](../../testing/ios/IosUnitTests/) +directory contains an Xcode container project to execute the test. -See the [iOS unit test README](https://github.com/flutter/engine/blob/main/testing/ios/IosUnitTests/README.md) +See [`testing/ios/IosUnitTests/README.md`](../../testing/ios/IosUnitTests/README.md) for details on adding new test files. The engine repo has a unified build system to build C, C++, Objective-C, Objective-C++, and Java files using [GN](https://gn.googlesource.com/gn/) and [Ninja](https://ninja-build.org/). Since GN and Ninja has to build the C++ dependencies that the Objective-C classes reference, the tests aren't built by -the Xcode project in https://github.com/flutter/engine/tree/main/testing/ios/IosUnitTests. +the Xcode project in [`testing/ios/IosUnitTests`](../../testing/ios/IosUnitTests/). Instead, the engine provides the script: -``` +```sh testing/run_tests.py --type=objc ``` @@ -231,14 +227,13 @@ mock all other dependencies with OCMock. The OCMock library is available as a test dependency when writing XCTests for the engine. -### End-to-end tests +### End-to-end tests (iOS Embedder) End-to-end tests exercise the entire iOS embedding with the C++ engine on a headless iOS simulator. It's an integration test ensuring that the engine as a whole on iOS is functioning correctly. -The project containing the iOS end-to-end engine test is at -https://github.com/flutter/engine/tree/main/testing/ios_scenario_app/ios. +The project containing the iOS end-to-end engine test is at [`testing/ios_scenario_app/ios`](../../testing/ios_scenario_app/ios/). This test project is build similarly to a normal debug Flutter app. The Dart code is bundled in JIT mode and is brought into Xcode with a `.framework` @@ -246,7 +241,7 @@ dependency on the prebuilt local engine. It's then installed and executed on a simulator via Xcode. Unlike a normal Flutter app, the Flutter framework on the Dart side is a -lightweight fake at https://github.com/flutter/engine/tree/main/testing/ios_scenario_app/lib +lightweight fake at [`testing/ios_scenario_app/lib`](../../testing/ios_scenario_app/lib/). that implements some of the basic functionalities of `dart:ui` Window rather than using the real Flutter framework at `flutter/flutter`. @@ -256,35 +251,35 @@ The end-to-end test can be executed by running: testing/ios_scenario_app/run_ios_tests.sh ``` -Additional end-to-end instrumented tests can be added to https://github.com/flutter/engine/tree/main/testing/ios_scenario_app/ios/Scenarios/ScenariosTests. +Additional end-to-end instrumented tests can be added to [`testing/ios_scenario_app/ios/Scenarios/ScenariosTests`](../../testing/ios_scenario_app/ios/Scenarios/ScenariosTests/). If supporting logic is needed for the test case, it can be added to the -Android app under-test in https://github.com/flutter/engine/tree/main/testing/ios_scenario_app/ios/Scenarios/Scenarios -or to the fake Flutter framework under-test in https://github.com/flutter/engine/tree/main/testing/ios_scenario_app/lib. +Android app under-test in [`testing/ios_scenario_app/ios/Scenarios/Scenarios`](../../testing/ios_scenario_app/ios/Scenarios/Scenarios/). +or to the fake Flutter framework under-test in [`testing/ios_scenario_app/lib`](../../testing/ios_scenario_app/lib/). As best practice, favor adding unit tests if possible since end-to-end tests are, by nature, non-hermetic, slow and flaky. End-to-end tests on iOS are executed during pre-submit on our CI system when -submitting PRs to the `flutter/engine` repository. +submitting PRs. ## Dart - dart:ui -If you edit `.dart` files in https://github.com/flutter/engine/tree/main/lib/ui, -you're working on the 'dart:ui' package which is the interface between -the C++ engine and the Dart Flutter framework. +If you edit `.dart` files in [`lib/ui`](../../lib/ui/) you're working on the +`dart:ui` package which is the interface between the C++ engine and the Dart +Flutter framework. -### Unit tests +### Unit tests (Dart) -Dart classes in https://github.com/flutter/engine/tree/main/lib/ui have matching -unit tests at https://github.com/flutter/engine/tree/main/testing/dart. +Dart classes in [`lib/ui`](../../lib/ui/) have matching unit tests at +[`testing/dart`](../../testing/dart/). When editing production files in the 'dart:ui' package, add to or create a test file in `testing/dart`. To run the Dart unit tests, use the script: -``` +```sh testing/run_tests.py --type=dart ``` @@ -317,4 +312,4 @@ Assuming your `flutter` and `engine` working directories are siblings, you can r ## Web engine -Web tests are run via the `felt` command. More details can be found in [lib/web_ui/README.md](https://github.com/flutter/engine/blob/main/lib/web_ui/README.md#hacking-on-the-web-engine). +Web tests are run via the `felt` command. More details can be found in [lib/web_ui/README.md](../../lib/web_ui/README.md).