{"id":21365136,"url":"https://github.com/altinn/app-localtest","last_synced_at":"2025-07-13T04:31:44.997Z","repository":{"id":73736461,"uuid":"595054406","full_name":"Altinn/app-localtest","owner":"Altinn","description":"Solution for testing apps locally on your own machine","archived":false,"fork":false,"pushed_at":"2024-04-11T18:14:24.000Z","size":1189,"stargazers_count":5,"open_issues_count":31,"forks_count":12,"subscribers_count":17,"default_branch":"main","last_synced_at":"2024-04-12T15:07:00.260Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Altinn.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2023-01-30T09:50:51.000Z","updated_at":"2024-04-15T08:41:15.259Z","dependencies_parsed_at":"2024-03-01T09:45:27.699Z","dependency_job_id":"1e2021ad-075a-4ea1-9fdf-efaa7720ecc6","html_url":"https://github.com/Altinn/app-localtest","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Altinn%2Fapp-localtest","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Altinn%2Fapp-localtest/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Altinn%2Fapp-localtest/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Altinn%2Fapp-localtest/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Altinn","download_url":"https://codeload.github.com/Altinn/app-localtest/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225855965,"owners_count":17534967,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-22T07:09:49.920Z","updated_at":"2025-07-13T04:31:44.980Z","avatar_url":"https://github.com/Altinn.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"## Local testing of apps\n\nThese are some of the required steps, tips, and tricks when it comes to running an app on a local machine. The primary goal is to be able to iterate over changes and verifying them without needing to deploy the app to the test environment.\n\n- [Prerequisites](#prerequisites)\n- [Setup](#setup)\n  - [Clone the repository](#clone-the-repository)\n  - [Option A: Start the containers using podman](#option-a-start-the-containers-using-podman)\n  - [Option B: Start the containers using Docker](#option-b-start-the-containers-using-docker)\n  - [Option C (preview): Automatic detection](#option-c-preview-automatic-detection)\n  - [Start your app](#start-your-app)\n- [Changing configuration](#changing-configuration)\n- [Multiple apps at the same time (running LocalTest locally)](#multiple-apps-at-the-same-time-running-localtest-locally)\n- [Changing test data](#changing-test-data)\n  - [Add a missing role for a test user](#add-a-missing-role-for-a-test-user)\n- [Known issues](#known-issues)\n  - [Localtest reports that the app is not running even though it is](#localtest-reports-that-the-app-is-not-running-even-though-it-is)\n\n### Prerequisites\n\n1. .NET SDK matching your service (the latest App Template uses [.NET 8 SDK](https://dotnet.microsoft.com/download/dotnet/8.0), older versions may also require [.NET 6 SDK](https://dotnet.microsoft.com/download/dotnet/6.0))\n2. Newest [Git](https://git-scm.com/downloads)\n3. A code editor - we like [Visual Studio Code](https://code.visualstudio.com/Download)\n    - Also\n      install [recommended extensions](https://code.visualstudio.com/docs/editor/extension-gallery#_workspace-recommended-extensions) (\n      f.ex. [C#](https://marketplace.visualstudio.com/items?itemName=ms-vscode.csharp))\n4. Tooling to run containers:  \n    - [Podman](https://podman.io)* (optionally with [Podman Desktop](https://podman-desktop.io))\n    - [Docker Desktop](https://www.docker.com/products/docker-desktop) (Windows and Mac) This might require you to purchase a license. \n    - Linux/WSL users can also use native Docker.\n  \n \u003e [!NOTE] \n \u003e On Mac with Apple silicone (M-series CPU), [vfkit](https://github.com/crc-org/vfkit?tab=readme-ov-file#installation) might be needed - consult the install guide/requirements for your container toolkit\n\n\n\u003e [!WARNING]\n\u003e *Podman on Windows/WSL2 can be tricky. If faced with the same issue as described in https://github.com/Altinn/app-localtest/issues/84, please apply the following (tested on Podman 4.9.2 and 5.1.1):\n\u003e * Install the Podman Machine with \"user-mode networking\" enabled (the setting for root/rootless seems not to have an impact)\n\u003e * Apply local updates to `podman-compose.yml` and `src\\appsettings.Podman.json` replacing `host.docker.internal` with `\u003cyour-hostname\u003e.local` (obtained by running `hostname` in the windows host commandline).  \n\u003e   e.g. in `src\\appsettings.Podman.json` the config `\"LocalAppUrl\": \"http://host.docker.internal:5005\",` becomes `\"LocalAppUrl\": \"http://AAD-123456789.local:5005\",` if your hostname is `AAD-123456789`\n\u003e \n\u003e If you have special networking needs (VPN), additional settings might be needed in WSL2/Podman. Please consult their respective doc/forums. https://learn.microsoft.com/en-us/windows/wsl/wsl-config#wslconfig and https://github.com/containers/podman/blob/main/docs/tutorials/basic_networking.md are good starting-ponts.\n\n### Setup\n\n#### Clone the repository\n\n```shell\ngit clone https://github.com/Altinn/app-localtest\ncd app-localtest\n ```\n\n#### Option A: Start the containers using podman\n\nThis mode supports running one app at a time. If you need to run multiple apps at once, stop the localtest container with `podman stop localtest` and follow the instructions below to run LocalTest locally outside Docker/Podman.\n\n\u003e [!IMPORTANT]\n\u003e If you are using an mac with either a M1, M2 or M3 chip you may need to use `applehv` instead of `qemu` as the podman machine driver. \n\u003e This can be done by setting the environment variable `CONTAINERS_MACHINE_PROVIDER` to `applehv` before running the command below.\n\u003e To add this to your zsh profile run the following command: `echo \"export CONTAINERS_MACHINE_PROVIDER=applehv\" \u003e\u003e ~/.zprofile`\n\u003e If you are using Podman Desktop you also need to add these lines in `~/.config/containers/containers.conf` (check if the `[machine]` section already exists):\n\u003e  \n\u003e ```\n\u003e [machine]\n\u003e   provider = \"applehv\"\n\u003e ```\n\nStart the containers with the following command:\n\n```shell\npodman compose --file podman-compose.yml up -d --build\n```\n\nOptionally, if you want access to Grafana and a local monitoring setup based on OpenTelemetry:\n\n```shell\npodman compose --file podman-compose.yml --profile \"monitoring\" up -d --build\n# Grafana should be available at http://local.altinn.cloud:8000/grafana\n# Remember to enable the 'UseOpenTelemetry' configuration flag in the appsettings.json of the app\n```\n\n\u003e [!NOTE]\n\u003e If you are using linux or mac you can use the Makefile to build and run the containers.\n\u003e \n\u003e ```shell\n\u003e make podman-start-localtest\n\u003e ```\n\n\u003e [!IMPORTANT]\n\u003e Are you running podman version \u003c 4.7.0 you need to use the following command instead:\n\u003e \n\u003e ```shell\n\u003e podman-compose --file podman-compose.yml up -d --build\n\u003e ```\n\u003e \n\u003e or the make command:\n\u003e \n\u003e ```shell\n\u003e make podman-compose-start-localtest\n\u003e ```\n\nLocaltest should now be runningn on port 8000 and can be accessed on \u003chttp://local.altinn.cloud:8000\u003e.\n\n#### Option B: Start the containers using Docker\n\nThis mode supports running one app at a time. If you need to run multiple apps at once, stop the localtest container with `docker stop localtest` and follow the instructions below to run LocalTest locally outside Docker.\n\n```shell\ndocker compose up -d --build\n```\n\nOptionally, if you want access to Grafana and a local monitoring setup based on OpenTelemetry:\n\n```shell\ndocker compose --profile \"monitoring\" up -d --build\n# Grafana should be available at http://local.altinn.cloud/grafana\n# Remember to enable the 'UseOpenTelemetry' configuration flag in the appsettings.json of the app\n```\n   \n\u003e [!NOTE]\n\u003e If you are using linux or mac you can use the Makefile to build and run the containers.\n\u003e \n\u003e ```shell\n\u003e make docker-start-localtest\n\u003e ```\n\nLocaltest should now be runningn on port 80 and can be accessed on \u003chttp://local.altinn.cloud:80\u003e.\n\n#### Option C (preview): Automatic detection\n\nThere is a preview helper script that will execute the correct commands in a cross-platform way.\nEither docker or podman must be installed.\n\n```shell\n./run.cmd\n```\n\nOptionally, if you want access to Grafana and a local monitoring setup based on OpenTelemetry:\n\n```shell\n./run.cmd -m\n```\n\nIf the localtest setup is already running, it will restart.\n\nTo stop localtest\n```shell\n./run.cmd stop\n```\n\n#### Start your app\n\n_This step requires that you have already [set up an app](https://docs.altinn.studio/nb/altinn-studio/guides/development/basic-form/) and [cloned the app](https://docs.altinn.studio/nb/altinn-studio/guides/development/local-dev/) to your local environment._\n\nMove into the `App` folder of your application.\n\nExample: If your application is named `my-awesome-app` and is located in the folder `C:\\my_applications`, run the following command:\n\n```shell\ncd C:\\my_applications\\my-awasome-app\\App\n```\n\nRun the application:\n\n ```shell\n dotnet run\n```\n\nThe app and local platform services are now running locally. The app can be accessed on \u003chttp://local.altinn.cloud\u003e.\n\nLog in with a test user, using your app name and org name. This will redirect you to the app.\n\n### Changing configuration\n\nThe Docker Compose config can be changed with local environment variables. There is a\ntemplate file for the `.env` file [here](./.env.template), rename it to `.env` and\nuncomment some variables that you want different values for.\n\nSometimes the local environment have another service running on port 80, so you might need to change this.\n\n```dotenv\nALTINN3LOCAL_PORT=80\n```\n\nIf you want to see the storage files on disk (instead of reading them through the browser), change this to a local\npath on your computer (ensure that it exists)\n\n```dotenv\nALTINN3LOCALSTORAGE_PATH=C:/AltinnPlatformLocal/\n```\n\nIf you want to use another domain than `local.altinn.cloud` for local testing you could do that this way:\n\n```dotenv\nTEST_DOMAIN=local.altinn.cloud\n```\n\n### Multiple apps at the same time (running LocalTest locally)\n\nThe setup described above (LocalTest running in Docker) currently only supports one app at a time. If you find\nyourself needing to run multiple apps at the same time, or if you need to debug or develop LocalTest, a local setup is\npreferred.\n\n:information_source: If you're already running LocalTest in Docker, be sure to stop the container with `docker stop localtest`\n\n**Configuration of LocalTest**\nThe LocalTest application acts as an emulator of the Altinn 3 platform services. It provides things like authentication,\nauthorization and storage. Everything your apps will need to run locally.\n\nSettings (under `LocalPlatformSettings`):\n\n- `LocalAppMode` - (default `file`) If set to `http`, LocalTest will find the active app configuration and policy.xml\n  using apis exposed on `LocalAppUrl`. (note that this is a new setting needs to be added manually under\n  `LocalPlatformSettings`, it might also require updates to altinn dependencies for your apps in order to support\n  this functionality)\n- `LocalAppUrl` - If `LocalAppMode` == `\"http\"`, this URL will be used instead of `AppRepositoryBasePath` to find apps\n  and their files. Typically the value will be `\"http://localhost:5005\"`\n- `LocalTestingStorageBasePath` - The folder to which LocalTest will store instances and data being created\n  during testing.\n- `AppRepositoryBasePath` - The folder where LocalTest will look for apps and their files\n  if `LocalAppMode` == `\"file\"`. This is typically the parent directory where you checkout all your apps.\n- `LocalTestingStaticTestDataPath` - Test user data like profile, register and\n  roles. (`\u003cpath to altinn-studio repo\u003e/testdata/`)\n\nThe recommended way of changing settings for LocalTest is through\n[user-secrets](https://docs.microsoft.com/en-us/aspnet/core/security/app-secrets?view=aspnetcore-6.0\u0026tabs=windows#set-a-secret).\nUser secrets is a set of developer specific settings that will overwrite values from the `appsettings.json` file when\nthe application is started in developer \"mode\". The alternative is to edit the `appsettings.json` file directly. Just be\ncareful not to commit developer specific changes back to the repository.\n\n- Define a user secret with the following command:  (make sure you are in the LocalTest folder)\n   ```bash\n   dotnet user-secrets set \"LocalPlatformSettings:AppRepositoryBasePath\" \"C:\\Repos\"\n   ```\n  Run the command for each setting you want to change.\n- Alternatively edit the appsettings.json file directly:\n    - Open `appsettings.json` in the `LocalTest` folder in an editor, for example in Visual Studio Code\n    - Change the setting `\"AppRepsitoryBasePath\"` to the full path to your app on the disk.\n    - Change other settings as needed.\n    - Save the file.\n\nFinally, start the local platform services (make sure you are in the `/src` folder)\n\n```bash\ncd /src\ndotnet run\n```\n\n### Changing test data\n\nIn some cases your application might differ from the default setup and require custom changes to the test data\navailable.\nThis section contains the most common changes.\n\n#### Add a missing role for a test user\n\nThis would be required if your app requires a role which none of the test users have.\n\n1. Identify the role list you need to modify by noting the userId of the user representing an entity, and the partyId of\n   the entity you want to represent\n2. Find the correct `roles.json` file in `testdata/authorization/roles` by navigating\n   to `User_{userID}\\party_{partyId}\\roles.json`\n3. Add a new entry in the list for the role you require\n\n  ```\n  {\n    \"Type\": \"altinn\",\n    \"value\": \"[Insert role code here]\"\n  }\n  ```\n\n4. Save and close the file\n5. Restart LocalTest\n\n### k6 testing\n\nIn the k6 folder there is a sample loadtest that can be adapted to run automated tests against a local app\nIt was created to simulate workloads and test monitoring and instrumentation.\n\n```shell\ncp k6/loadtest.sample.js k6/loadtest.js\n# Now make edits to k6/loadtest.js to fit your application\n\n# To run, either\n./run.cmd k6\n# or \ndocker run --rm -i --net=host grafana/k6:master-with-browser run - \u003ck6/loadtest.js\n```\n\nFor a decent editing experience, run `npm install` and use a editor with JS support.\n\n### Known issues\n\n#### Localtest reports that the app is not running even though it is\n\nIf localtest and you app is running, but localtest reports that the app is not running, it might be that the port is not open in the firewall.\n\nYou can verify if the app is running by opening `http://localhost:5005/\u003capp-org-name\u003e/\u003capp-name\u003e/swagger/index.html` (remember to replace `\u003capp-org-name\u003e` and `\u003capp-name\u003e` with the correct values).\n\nIf this is the case you can open a Windows Powershell as administrator and run the script `OpenAppPortInHyperVFirewall.ps1` located in the `scripts` folder.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faltinn%2Fapp-localtest","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faltinn%2Fapp-localtest","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faltinn%2Fapp-localtest/lists"}