This guide helps you get started running and interacting with a local development server and tests. If you are a Full Time SWE onboarding, first check out the links/tutorials/account-settup detailed in New Full Time SWE Onboarding Material.
Start here! This step is a prerequisite for everything that follows, even if you only want to interact with a local server without pushing changes. If you're working in Windows, check out Getting started with Windows.
- 4.Install Docker
- On Mac
- Run Docker Desktop and go to Preferences > Resources to increase max RAM for containers to at least 4GB (ideally 6GB), otherwise sbt compiles can get killed before completing and produce strange runtime behavior.
You may use whichever IDE you prefer, though DO NOT use the IDE's built-in sbt (Scala Build Tool) shell if it has one. Instead, run
bin/sbtto bring up an sbt shell inside the Docker container. The sbt shell allows you to compile, run tests, and run any other sbt commands you may need
The easiest way to get IntelliJ to index the project correctly is to install the Scala plugin and open the project by specifying the build.sbt file in IntelliJ's open existing project dialog. If this isn't done correctly IntelliJ probably won't load library code correctly and will complain that it can't find symbols imported from libraries.
This setup will only include the files under (.../server), therefore, if you would like to edit other files under .../civiform, you need to add additional modules manually:
- Go to File/Project Structure,
- Select modules
sourcesare selected in second and third column,
- Click on + on the right handside to add all folders under civiform except "server" to the content roots
bin/vscode-setupto generate a pom.xml file that allows VSCode to resolve dependencies
- 3.Open the workspace file
- 4.Metals automatically detects the project. Click
Import Buildat the prompt.
sbtat the prompt for multiple build definitions.
- If source code isn't being indexed / symbols aren't found, you may need to clean the Java workspace. Trigger the command pallet and select
Java: Clean Java Language Server Workspace
- If a new dependency is added, the
pom.xmlfile may be out of date. You'll need to either add the dependancies manually, or re-run the bin/vscode-setup script to regenerate the file.
VSCode uses the following files
- server/pom.xml (maven dependancies for symbols)
- server/.settings/*. (generated by
- civiform.code-workspace (opens the top level directory, and server)
Note: the project makes heavy use of shell scripts for development tasks. Run
bin/helpto see a list of them.
- 1.To run the application, navigate to the
civiformdirectory you created when you cloned the repo and run the following:bin/run-devTo run the application using Azure instead of AWS, run:bin/run-dev –-azure
This will start up a dev instance of the application that uses Azurite, the Azure emulator, instead of local stack, the AWS emulator. This script sets an environment variable,
STORAGE_SERVICE_NAMEtelling the application to run using the Azure emulator instead of AWS.
Tip: Once you have the local server working, you may want to set
USE_LOCAL_CIVIFORM=1by default in your environment. This will speed up reruns by not always redownloading the latest docker images (1-2GB each) which is not usually necessary.
- 1.Once you see "Server started" in your terminal (it will take some time for the server to start up), you can access the app in a browser at http://localhost:9000. Be patient on the initial page load since it will take some time for all the sources to compile.
For login and file upload to work with your local server, you need to edit your
/etc/hostsfile to include the following:
# Required for test AWS S3 bucket
This provides a local IP route for the 'dev-oidc', 'azurite', and 'localstack' hostnames.
Creating questions and programs in CiviForm is a bit time consuming to do manually with the UI, so in dev mode there is a controller action that generates several for you. You can access this feature at
If you'd like to run a specific test or set of tests, and/or save sbt startup time each time you run the test(s), use the following steps. This is recommended for developer velocity.
- 1.Bring up an sbt shell inside the Docker container by running:bin/sbt-test
- 2.Run any sbt commands! For example:testOnly services.question.types.QuestionDefinitionTesttest
If you'd like to run a specific test or set of tests, run the following:
bin/run-ts-tests file1.test.ts file2.test.ts
- 1.Bring up the local test environment using the AWS emulator. Leave this running:bin/run-browser-test-env
- 2.Once you see "Server started" in the terminal from the above step, in a separate terminal run the tests in a docker container:bin/run-browser-testsOr, to run a test in a specific file, you can pass the file path relative to the
Browser tests are heavy handed and can take a while to run. You can focus the run to only execute a single
describesuite per file by prefixing it with
To create Questions and Programs that use them, you need to log in as a "Program and Civiform Admin" through http://localhost:9000/loginForm .
You can return to that screen to switch to a Guest user and back again to an Admin as needed.
To generate coverage report, run the following:
Navigate to server/code-coverage/report/html/index.html and see the detailed report of the code coverage data and also dig deep to see how much your implemented classes are covered.