These are the common tasks involved when working on features, enhancements, bug fixes, etc. for TEAMMATES.
The instructions in all parts of this document work for Linux, OS X, and Windows, with the following pointers:
./gradlew
to gradlew.bat
if you are using Windows.If you encounter any problems during the any of the processes, please refer to our troubleshooting guide before posting a help request on our issue tracker.
Dev server is the server run in your local machine.
Front-end dev server is the Angular-based server handling the user interface.
First, you need to compile some type definitions from the back-end to be used in this dev server. Run the following command:
./gradlew generateTypes
To start the dev server, run the following command until you see something like 「wdm」: Compiled successfully.
:
npm run start
The dev server URL will be given at the console output, e.g. http://localhost:4200
.
To stop the dev server, press Ctrl + C
.
The dev server is run in watch mode by default, i.e. any saved change to the front-end code will be propagated to the server immediately.
The dev server is also run in live reload mode by default, i.e. any saved change to the front-end code will automatically load all dev server web pages currently being opened. To disable this behaviour, run the dev server as follows instead:
npm run start -- --live-reload=false
Back-end dev server is the Jetty-based server handling all the business logic, including data storage.
In order for the back-end to properly work, you need to have a running database instance and a full-text search service instance (if you are supporting one). The instances can either be a local emulator or a running production instance.
The details on how to run them locally can be found here (for local Datastore emulator) and here (for full-text search service).
If you have access to Docker, we have a Docker compose definition to run those services:
docker-compose up -d
To start the server in the background, run the following command
and wait until the task exits with a BUILD SUCCESSFUL
:
./gradlew serverRun &
To start the server in the foreground (e.g. if you want the console output to be visible), run the following command instead:
./gradlew serverRun
The dev server URL will be http://localhost:8080
.
If you started the server in the background, use any method available in your OS to stop the process at port 8080
.
If the server is running in the foreground, press Ctrl + C
(or equivalent in your OS) to stop it or run the above command in a new console.
In order for the dev server to be able to serve both the front-end and the back-end of the application, the front-end files need to be bundled and transpiled (afterwards built
).
Run the following commands to build the front-end files for the application's use in production mode:
# Generate type definition file from back-end
./gradlew generateTypes
# Bundle, transpile, and minify front-end files
npm run build
After this, the back-end dev server will also be able to serve the front-end.
This instruction set applies for both dev server and production server, with slight differences explained where applicable.
http://localhost:8080
.
http://localhost:4200
. However, a back-end server needs to be running in order for the authentication logic to work./web/page/somePage
is accessible in dev server at http://localhost:8080/web/page/somePage
.In dev server, it is also possible to "log in" without UI (e.g. when only testing API endpoints). In order to do that, you need to submit the following API call:
POST http://localhost:8080/devServerLogin?email=test@example.com
where email=test@example.com
can be replaced as appropriate.
The back-end server will return cookies which will subsequently be used to authenticate your requests.
To "log out", submit the following API call:
GET http://localhost:8080/logout
The Datastore emulator is an essential tool that we use to locally simulate production Datastore environment during development and testing of relevant features. For more information about the Datastore emulator, refer to Google's official documentation.
To stop the Datastore emulator, use any method available in your OS to locate and stop the process at the port used for the emulator.
If you are using the Cloud SDK method, you can use Ctrl + C
in the console to stop the process. If the emulator fails to stop gracefully, use the previously described method.
There are two big categories of testing in TEAMMATES:
src/test/resources/testng-component.xml
(back-end) and src/web/jest.config.js
(front-end).src/e2e/resources/testng-e2e.xml
. To learn more about E2E tests, refer to this document.To run all front-end component tests in watch mode (i.e. any change to source code will automatically reload the tests), run the following command:
npm run test
To run all front-end component tests once and generate coverage data afterwards, run the following command:
npm run coverage
To run an individual test in a test file, change it
in the *.spec.ts
file to fit
.
To run all tests in a test file (or all test files matching a pattern), you can use Jest's watch mode and filter by filename pattern.
Back-end component tests follow this configuration:
Test suite | Command | Results can be viewed in |
---|---|---|
Component tests | ./gradlew componentTests | {project folder}/build/reports/tests/componentTests/index.html |
Any individual component test | ./gradlew componentTests --tests TestClassName | {project folder}/build/reports/tests/componentTests/index.html |
You can generate the coverage data with jacocoReport
task after running tests, e.g.:
./gradlew componentTests jacocoReport
The report can be found in the build/reports/jacoco/jacocoReport/
directory.
Staging server
is the server instance you set up on Google App Engine for hosting the app for testing purposes.
For most cases, you do not need a staging server as the dev server has covered almost all of the application's functionality. If you need to deploy your application to a staging server, refer to this guide.
Client scripts are scripts that remotely manipulate data on a Google Cloud Datastore instance. They are run as standard Java applications.
Most of developers may not need to write and/or run client scripts but if you are to do so, take note of the following:
There are several files used to configure various aspects of the system.
Main: These vary from developer to developer and are subjected to frequent changes.
build.properties
: Contains the general purpose configuration values to be used by the web API.config.ts
: Contains the general purpose configuration values to be used by the web application.test.properties
: Contains the configuration values for the test driver.
test.properties
; one for component tests and one for E2E tests.client.properties
: Contains some configuration values used in client scripts.app.yaml
: Contains the configuration for deploying the application on GAE.Tasks: These do not concern the application directly, but rather the development process.
build.gradle
: Contains the back-end third-party dependencies specification, as well as configurations for automated tasks/routines to be run via Gradle.gradle.properties
, gradle-wrapper.properties
: Contains the Gradle and Gradle wrapper configuration.package.json
: Contains the front-end third-party dependencies specification, as well as configurations for automated tasks/routines to be run via NPM.angular.json
: Contains the Angular application configuration.GitHub Actions: These are workflow files for GitHub Actions. They are placed under .github/workflows
directory.
component.yml
: Configuration for component tests.e2e.yml
: Configuration for E2E tests.e2e-cross.yml
: Configuration for cross-browser E2E tests.lnp.yml
: Configuration for load & performance tests.dev-docs.yml
: Configuration for developer documentation site.Static Analysis: These are used to maintain code quality and measure code coverage. See Static Analysis.
static-analysis/*
: Contains most of the configuration files for all the different static analysis tools.Other: These are rarely, if ever will be, subjected to changes.
logging.properties
: Contains the java.util.logging configuration.web.xml
: Contains the web server configuration, e.g servlets to run, mapping from URLs to servlets, security constraints, etc.cron.yaml
: Contains the cron jobs specification.queue.yaml
: Contains the task queues configuration.index.yaml
: Contains the Google Cloud Datastore indexes configuration.