Skip to content

Latest commit

 

History

History
131 lines (80 loc) · 3.95 KB

DEVELOPMENT.md

File metadata and controls

131 lines (80 loc) · 3.95 KB
Raw

Development with Artemis

Artemis can be used to jump-start a new web application.

Common Setup

Artemis supports both local and containerized development. Regardless of which is used, the following common setup steps should be followed.

Code Repository

Fork the code repository and pull down the latest with git clone <PATH_TO_FORKED_REPOSITORY>.

Create a custom .env file:

cp .env.example .env

Review the environment file and follow commented documentation to populate the required values:

vim .env

System Ports and Local DNS

Artemis runs a development webserver on a local port. The default port is specified in the .env file, but can be changed.

For websocket support, Artemis must be reachable through local DNS at https://artemis.test. A local DNS manager with SSL support like Puma Dev makes this easy.

If using Puma Dev, this can be accomplished by creating a new puma dev config file:

source .env
echo $ARTEMIS_WEB_PORT > ~/.puma-dev/artemis
echo $ARTEMIS_API_PORT > ~/.puma-dev/artemis-api

Docker Environment

A container-based development environment is available using docker and docker compose. Once the docker platform is installed, build and run the containers:

bin/docker-dev/build dev
bin/docker-dev/up

Local Environment

Elixir

Artemis requires a specific version of Elixir. The version is always specified in .env.example.

An Elixir version manager like asdf for elixir or kiex can make it easy to manage multiple Elixir versions in the same development environment.

Node

Artemis requires a specific version of NodeJS. The version is always specified in .env.example.

A Node version manager like asdf for node or nvm can make it easy to manage multiple Node versions in the same development environment.

PostgreSQL

Artemis requires PostgreSQL >= 9.6.

It can be run inside a docker container or installed locally on the command-line using brew install postgresql or with a standalone application like Postico.

Browser Testing

Artemis requires headless chrome for browser-based testing.

It can be installed locally on the command-line using brew cask install chromedriver.

Initial Configuration

Before running the application the first time, execute bin/local/reset-all.

Warning: The bin/local/reset-all script is destructive. It will drop current dependencies and pull down the latest, and it will drop databases and recreate them with seed data.

Testing

Docker

If not running already, start an instance of the development environment:

bin/docker-dev/up

Then execute the tests using:

bin/docker-dev/test

Local Development

Unit Tests

Comprehensive unit tests are included in Artemis. To run them use:

bin/local/test <app> <file>:<line-number>

For example:

bin/local/test # Run all tests on all applications
bin/local/test artemis_web # Only run tests for artemis_web application
bin/local/test artemis_web test/artemis_web/controllers/feature_controller_test.exs:14 # Only run a specific test

Or if you prefer to use mix test directly, make sure environmental variables are exported first:

set -a && source .env && set +a
cd apps/artemis_web
mix test # Run all tests in application artemis_web
mix test test/artemis_web/controllers/feature_controller_test.exs:14 # Only run a specific test

Browser Tests

Before running browser tests, start the headless chrome server with chromedriver --headless.

By default, browser tests are only run in the CI environment. To run them use:

mix test --include browser