SkillTree Docs

# Development Environment

We recommend developing SkillTree in a *nix environment.

# Prerequisites

# Development Overview

The tech stack is large but to get started you will need to be familiar (but more likely experienced) with these core technologies:

# Development

The skills-service project encapsulates code for the SkillTree dashboard, REST apis and Skills Display views.

# Get, build, and test

First things first, fork and checkout the code (please see the Contribution Steps), build it and run all of the unit and integration tests. Then we'll discuss development and testing steps.

git clone <github>:skills-service.git

To build the project, run the unit tests and the backend integration tests:

cd skills-service
mvn install

Since this process runs all of the service integration tests it will take a while (5 to 20 minutes depending on your hardware).

SkillTree uses maven (opens new window) and npm (opens new window) for its dependency management and to facilitate the build lifecycle. Let's get familiar with the project's layout:

skills-service
└───service
│   │   pom.xml
|   └───target
|   |   skills-service-<version>.jar
|   |   ....
└───dashboard
|   │   pom.xml
|   │   package.json
|   |   ....
└───e2e-tests
|   │   package.json
|   |   ....
└─── pom.xml

The runtime artifact is a spring boot (opens new window) application and will be created in service/skills-service-<version>.jar; we ran mvn install to generate this artifact and the following sequence of steps were performed:

  • Build dashboard web application: npm run build in dashboard project
  • Compile Java and Groovy classes in the service project: mvn compile
  • Copy the built dashboard app to service/src/main/resources/public so the spring boot app can host the dashboard web-application
  • Generate runtime artifact: mvn package in the service project

Of course this doesn't cover the entire build cycle so please familiarize yourself with all of the pom.xml and package.json files. Now that you have the runtime artifact, you can start the SkillTree dashboard and service using the following command:

java -jar service/target/skills-service-<version>.jar

The app will run on http://localhost:8080 (opens new window), visit it to create an account, new project, subjects, skills, etc. To learn more about the features of the SkillTree dashboard, please visit the Dashboard Guide.

The SkillTree application will be started using default properties. Some things to note:

  • Spring datasource properties will need to be configured for connecting to an available PostgreSQL database using the following properties:
spring.datasource.url=jdbc:postgresql://localhost:5432/skills
spring.datasource.username=<username>
spring.datasource.password=<password>

# Cypress.io end-to-end tests

SkillTree utilizes the cypress.io (opens new window) framework to perform end-to-end tests and specifically verify features of the dashboard web application. Cypress tests are located in the e2e-tests project:

skills-service
|   ....
└───e2e-tests
|   │   package.json
|   └───cypress
|   |   └───integration
|   |   <dashboard test name>_spec.js
|   |   |   └───client-display
|   |   |   |   <client-display test name>_spec.js

The end-to-end tests stand-up the skills-service and the dashboard applications and then execute numerous tests against these web-applications to mimic users' actions.

To run cypress end-to-end tests (assumes that you have built the skills-service.jar via the previous step):

cd skills-service/e2e-tests
npm install

# start servers in the background: skills-service and client-display
npm run cyServices:start
# run cypress integration tests
npm run cy:run
# kill background servers
npm run cyServices:kill

TIP

Please note that you may need to clear DB tables if they were populated by the previous installation. Cypress tests purge all the user data except the dashboard root user, so if one was already created it will need to be manually deleted. The easiest way is to just delete all rows from the user_attrs table.

Buckle down as these tests will take a while to run. Generally only select tests are executed locally and all tests are performed in the CI lifecycle, in parallel.

TIP

Please note that ports 8080, 1025, and 1080 have to be available on your system

npm run cyServices:start command starts:

  • The programmatic service and the dashboard by utilizing the already built jar; will run on port 8080
  • A mock smtp server; will run on ports 1025 and 1080

Now that you can build and run integration tests let's discuss day-to-day development setup for the skills-service project.

# Day-to-day development

Most IDEs (Intellij, Eclipse, etc...) provide first-class support for maven projects so the very first step would be to import the skills-service project into your favorite IDE.

Please note that code additions will generally fall into these categories:

  1. Enhancing the skills-service programmatic REST API
  2. Making changes to the web-based dashboard application
# skills-service programmatic REST API

The code for the API can be found under skills-service/service which follows standard maven conventions.

The programmatic API tests reside in service/src/test/java and you can run all the service tests via

cd skills-service/service
mvn test

You can also run any of the tests using your favorite IDE.

TIP

SkillTree's overall testing strategy is to implement black-box integration tests and supplement with unit tests whenever an integration test is not possible.

Generally, programmatic API service development is facilitated via the integration/service tests .

Skills Service integration tests stand-up the skills-service application and then execute various endpoints, validating the result. These integration tests reside in the skills.intTests package and extend the DefaultIntSpec.groovy class.

DefaultIntSpec.groovy is annotated with the @SpringBootTest (opens new window) annotation which facilitates running the Spring Boot application, exposing endpoints on a random port.

A few things to note:

  • You should interact with the skills-service using the test client skills.intTests.utils.SkillsService class
    • Available via skills.intTests.utils.DefaultIntSpec#skillsService
    • SkillsService class represents an authenticated dashboard user
  • Runtime port can be retrieved via skills.intTests.utils.DefaultIntSpec#localPort but should rarely be used directly; instead please use skills.intTests.utils.DefaultIntSpec#skillsService instead
  • DefaultIntSpec setup and cleanup methods purge data from DB between each test case
  • Use the skills.intTests.utils.DefaultIntSpec#createService method if you need a new SkillsService instance
    • For example to represent another dashboard user

There are hundreds of tests in the skills.intTests package, please feel free to explore.

# Web-Based Dashboard

Steps to develop the web-based dashboard are:

  1. Stand up the service (programmatic API)
  2. Bring up the vite dev server
  3. Use browser and cypress tests to drive development

To stand up the service you can execute skills.SpringBootApp in the service project from your IDE.

If that's not an option you can always build a jar and run it from the command line:

java -jar service/target/skills-service-<version>.jar

At a minimum will need to set DB connection properties:

spring.datasource.url=jdbc:postgresql://localhost:5432/skills
spring.datasource.username=<username>
spring.datasource.password=<password>

The service will run on port 8080.

Next is to start the vite dev server in the dashboard project:

cd dashboard
npm run dev

This vite dev server will run on port 5173 and will make requests for data to the service running on port 8080.

Generally development is facilitated by writing cypress tests:

cd e2e-tests
npm run cy:open:dev

You can then start adding tests under e2e-tests/cypress/integration to an existing file or by creating a new file.

# Skills Display

Skills Display components provides a comprehensive visualization of a user's skill and progress profile! The code for the Skills Display is mostly encapsulated under dashboard/src/skills-display directory with an entry point of SkillsDisplay.vue Vue component.

SkillsDisplay.vue is used in various scenarios:

  • to show user's progress within a single project on the Progress & Ranking pages
  • served as a dedicated url to power skills-client (opens new window) libraries
  • server under several urls for testing purposes

There are three places that Sills Display need to be tested:

  • /test-skills-display/<project-id> - most of the cypress tests utilize this url; Skills Display is served natively and is customized for testing
  • /test-skills-client/<project-id> - Skills Display is served within an iframe simulating skills-client (opens new window)'s usage; see cypress tests for examples
  • /progress-and-rankings/projects/<project-id> - Dashboard's usage of skills-display to show user's progress and rankings for a single project

# Test Checklist

TIP

SkillTree's overall testing strategy is to implement black-box integration tests and supplement with unit tests whenever an integration test is not possible.

We like tests (especially integration tests), so please make sure you thoroughly test your code.
Prior to making a Pull Request make sure that ALL tests pass, once you push your branch GitHub Actions CI will execute all the service and Cypress tests.

Provide the following properties to run the service tests against PostgreSQL:

spring.datasource.url=jdbc:postgresql://localhost:5432/skills
spring.datasource.username=<username>
spring.datasource.password=<password>

On the command line it would look something like this:

mvn --batch-mode test -Dspring.datasource.url=jdbc:postgresql://postgres:5432/skills -Dspring.datasource.username=user -Dspring.datasource.password=pass

To run all the cypress tests:

cd skills-service/e2e-tests
npm install

# start servers in the background: skills-service and client-display to test
npm run cyServices:start
# run cypress integration tests
npm run cy:run
# kill background servers
npm run cyServices:kill
Last Updated: 11/20/2024, 5:10:03 PM