From 18913e7709867ea6814f019f25a4d8daa0d93501 Mon Sep 17 00:00:00 2001 From: Ryan Fu Date: Sun, 14 Aug 2022 12:17:58 -0700 Subject: [PATCH] Separated code blocks and added linking for testing directory (#15636) * Separated code blocks and added linking for testing directory * Updated links to relative links and added clearer wording for string placeholders --- .../gradle-cheatsheet.md | 53 ++++++++++++++----- 1 file changed, 39 insertions(+), 14 deletions(-) diff --git a/docs/contributing-to-airbyte/gradle-cheatsheet.md b/docs/contributing-to-airbyte/gradle-cheatsheet.md index e948b4397ccd5..12c050b235503 100644 --- a/docs/contributing-to-airbyte/gradle-cheatsheet.md +++ b/docs/contributing-to-airbyte/gradle-cheatsheet.md @@ -12,9 +12,12 @@ We have 3 ways of slicing our builds: In our CI we run **Build Platform** and **Build Connectors Base**. Then separately, on a regular cadence, we build each connector and run its integration tests. -We split Build Platform and Build Connectors Base from each other for a few reasons: 1. The tech stacks are very different. The Platform is almost entirely Java. Because of differing needs around separating environments, the Platform build can be optimized separately from the Connectors one. 2. We want to the iteration cycles of people working on connectors or the platform faster _and_ independent. e.g. Before this change someone working on a Platform feature needs to run formatting on the entire codebase \(including connectors\). This led to a lot of cosmetic build failures that obfuscated actually problems. Ideally a failure on the connectors side should not block progress on the platform side. 3. The lifecycles are different. One can safely release the Platform even if parts of Connectors Base is failing \(and vice versa\). +We split Build Platform and Build Connectors Base from each other for a few reasons: +1. The tech stacks are very different. The Platform is almost entirely Java. Because of differing needs around separating environments, the Platform build can be optimized separately from the Connectors one. +2. We want to the iteration cycles of people working on connectors or the platform faster _and_ independent. e.g. Before this change someone working on a Platform feature needs to run formatting on the entire codebase \(including connectors\). This led to a lot of cosmetic build failures that obfuscated actually problems. Ideally a failure on the connectors side should not block progress on the platform side. +3. The lifecycles are different. One can safely release the Platform even if parts of Connectors Base is failing \(and vice versa\). -Future Work: The next step here is to figure out how to more formally split connectors and platform. Right now we exploit behavior in `settings.gradle` to separate them. This is not a best practice. Ultimately, we want these two builds to be totally separate. We do not know what that will look like yet. +Future Work: The next step here is to figure out how to more formally split connectors and platform. Right now we exploit behavior in [settings.gradle](../../settings.gradle) to separate them. This is not a best practice. Ultimately, we want these two builds to be totally separate. We do not know what that will look like yet. ## Cheatsheet @@ -48,10 +51,10 @@ In order to "build" the project. This task includes producing all artifacts and For example all the following are valid. -```text -./gradlew build -SUB_BUILD=PLATFORM ./gradlew build -SUB_BUILD=CONNECTORS_BASE ./gradlew build +```shell +./gradlew build # builds the entire Airbyte project including every single connector supported +SUB_BUILD=PLATFORM ./gradlew build -x test # builds Airbyte Platform without running tests +SUB_BUILD=CONNECTORS_BASE ./gradlew build # builds all Airbyte connectors and runs unit tests ``` ### Formatting @@ -60,7 +63,7 @@ The build system has a custom task called `format`. It is not called as part of For example all the following are valid. -```text +```shell ./gradlew format SUB_BUILD=PLATFORM ./gradlew format SUB_BUILD=CONNECTORS_BASE ./gradlew format @@ -72,7 +75,7 @@ SUB_BUILD=CONNECTORS_BASE ./gradlew format This command just builds the docker images that are used as artifacts in the platform. It bypasses running tests. -```text +```shell SUB_BUILD=PLATFORM ./gradlew build ``` @@ -80,6 +83,13 @@ SUB_BUILD=PLATFORM ./gradlew build The Platform has 3 different levels of tests: Unit Tests, Acceptance Tests, Frontend Acceptance Tests. +| Test | Used | Description | +|:------------|:----:|:----------------------------------------------------------------------------------------------| +| Unit | X | Aims to test each component (e.g. a method function) | +| Integration | | Checks the data flow from one module to other modules | +| System | | Tests overall interaction of components, includes load, performance, reliability and security | +| Acceptance | X | Assess whether the Product is working for the user's viewpoint | + **Unit Tests** Unit Tests can be run using the `:test` task on any submodule. These test class-level behavior. They should avoid using external resources \(e.g. calling staging services or pulling resources from the internet\). We do allow these tests to spin up local resources \(usually in docker containers\). For example, we use test containers frequently to spin up test postgres databases. @@ -88,16 +98,21 @@ Unit Tests can be run using the `:test` task on any submodule. These test class- We split Acceptance Tests into 2 different test suites: -* Platform Acceptance Tests: These tests are a coarse test to sanity check that each major feature in the platform. They are run with the following command: `SUB_BUILD=PLATFORM ./gradlew :airbyte-tests:acceptanceTests`. These tests expect to find a local version of Airbyte running. For testing the docker version start Airbyte locally. For an example, see the [script](https://github.com/airbytehq/airbyte/blob/master/tools/bin/acceptance_test.sh) that is used by the CI. For Kubernetes, see the [script](https://github.com/airbytehq/airbyte/blob/master/tools/bin/acceptance_test_kube.sh) that is used by the CI. +* Platform Acceptance Tests: These tests are a coarse test to sanity check that each major feature in the platform. They are run with the following command: `SUB_BUILD=PLATFORM ./gradlew :airbyte-tests:acceptanceTests`. These tests expect to find a local version of Airbyte running. For testing the docker version start Airbyte locally. For an example, see the [acceptance_test script](../../tools/bin/acceptance_test.sh) that is used by the CI. For Kubernetes, see the [accetance_test_kube script](../../tools/bin/acceptance_test_kube.sh) that is used by the CI. * Migration Acceptance Tests: These tests make sure the end-to-end process of migrating from one version of Airbyte to the next works. These tests are run with the following command: `SUB_BUILD=PLATFORM ./gradlew :airbyte-tests:automaticMigrationAcceptanceTest --scan`. These tests do not expect there to be a separate deployment of Airbyte running. -These tests currently all live in `airbyte-tests` +These tests currently all live in [airbyte-tests](../.././airbyte-tests) **Frontend Acceptance Tests** -These are acceptance tests for the frontend. They are run with `SUB_BUILD=PLATFORM ./gradlew --no-daemon :airbyte-webapp-e2e-tests:e2etest`. Like the Platform Acceptance Tests, they expect Airbyte to be running locally. See the [script](https://github.com/airbytehq/airbyte/blob/master/tools/bin/e2e_test.sh) that is used by the CI. +These are acceptance tests for the frontend. They are run with +```shell +SUB_BUILD=PLATFORM ./gradlew --no-daemon :airbyte-webapp-e2e-tests:e2etest +``` +Like the Platform Acceptance Tests, they expect Airbyte to be running locally. See the [script](https://github.com/airbytehq/airbyte/blob/master/tools/bin/e2e_test.sh) that is used by the CI. + -These tests currently all live in `airbyte-webapp-e2e-tests`. +These tests currently all live in [airbyte-webapp-e2e-tests](../.././airbyte-webapp-e2e-tests) **Future Work** @@ -109,7 +124,14 @@ Our story around "integration testing" or "E2E testing" is a little ambiguous. O All connectors, regardless of implementation language, implement the following interface to allow uniformity in the build system when run from CI: -**Build connector, run unit tests, and build Docker image**: `./gradlew :airbyte-integrations:connectors::build` **Run integration tests**: `./gradlew :airbyte-integrations:connectors::integrationTest` +**Build connector, run unit tests, and build Docker image**: +```shell +./gradlew :airbyte-integrations:connectors::build +``` +**Run integration tests**: +```shell +./gradlew :airbyte-integrations:connectors::integrationTest +``` #### Python @@ -117,5 +139,8 @@ The ideal end state for a Python connector developer is that they shouldn't have We're almost there, but today there is only one Gradle command that's needed when developing in Python, used for formatting code. -**Formatting python module**: `./gradlew :airbyte-integrations:connectors::airbytePythonFormat` +**Formatting python module**: +```shell +./gradlew :airbyte-integrations:connectors::airbytePythonFormat +```