Skip to content

Latest commit

 

History

History
192 lines (119 loc) · 7.9 KB

TUTORIAL-PYTHON-CHIPYORG.md

File metadata and controls

192 lines (119 loc) · 7.9 KB
Raw

AppMap Tutorial: Mapping a Python Application in Visual Studio Code

This tutorial will walk you through the process of AppMapping an open source application chipy.org implemented in Python and Django. You will map this application with the AppMap for Visual Studio Code.

Prerequisites

  • Basic familiarity with git, Visual Studio Code, Python and Django
  • git and Docker installed in your environment (macOS, Windows+WSL, Linux)

Structure

This tutorial is split into three sections:

  • Install Visual Studio Code and the AppMap extension
  • Setup and build the chipy.org application in a Docker image
  • Setup, record and open AppMaps recorded from chipy.org tests

Walk-through video

Watch Walk-through Video

Install Visual Studio Code & the AppMap extension

  1. Install the official build of Visual Studio Code - visit the Visual Studio Code site
  2. Install AppMap for Visual Studio Code from the marketplace - visit AppMap in the Marketplace

Alternatively, install and start Visual Studio Code, open the Extensions tab and search for AppMap in the extensions list. Install the AppMap extension.

Build the chipy.org application

The Chicago Python User Group Website project comes with detailed setup instructions. The setup steps are described in this guide for your convenience.

Clone the repository

Start with a local clone of the chipy.org repository. In your working folder, clone the repo:

git clone https:/chicagopython/chipy.org.git

Open the chipy.org project in Visual Studio Code

Start Visual Studio Code and open the folder with the chipy.org repository. You should see the README.md and other files in the root folder.

chipy.org project in Visual Studio Code

Setup chipy.org with Docker

It is a good practice to setup and run applications before mapping them as it is easier to catch setup and build problems specific to the applications and their dependencies this way.

If you use Windows 10, consult the installation guide for setup of the build enviornment, specifically the make tool.

To build and run the application:

  1. Navigate to the chipy.org folder and run the setup command
make setup_env
  1. Start the application with
make up
  1. Migrate the database
make migrate
  • optionally, run make superuser to create a superuser if you plan to try the superuser support in the app

  1. Open the app in the browser. At this point, the application can be accessed on http://localhost:8000

  2. Run tests

make test

If you have encountered any problems during these steps, please consult the installation guide or contact us on Discord.

Setup AppMaps

The appmap Python package and the appmap.yml configuration file are required for recording AppMaps from tests.

Configure appmap.yml

The appmap package configuration is stored in an appmap.yml file in the root directory of Python projects. Create a new file called appmap.yml in the root folder of the chipy.org folder, and copy/paste these configuration lines in it. The file lists all modules and classes that will be recorded, in this example all objects in the chipy_org module:

name: chipy.org

packages:
- path: chipy_org

The format of appmap.yml is documented in the appmap-python documentation. appmap.yml can be fine tuned to include/exclude individual modules, classes and methods.

Install the appmap package in the Docker image

  1. Open shell in the running Docker image
make shell
  1. Install the appmap Python package
pip install appmap

Record and interact with AppMaps

Before proceeding, please check that

  • the chicopy.org application has been successfully built and running in a Docker container
  • the chicopy.org tests ran successfully
  • the appmap Python package has been successfully installed and configured in the running Docker image
  • you have Visual Studio Code running with the chipy.org project folder open

Run tests, record AppMaps

The AppMap setup is now complete and the application can be recorded when pytest tests are run. The recorder will be activated when the env variable APPMAP is set to true.

  1. In the running Docker image shell, run
APPMAP=true pytest
  1. Alternatively, run and record individual tests
APPMAP=true pytest chipy_org/apps/job_board/tests/test_views.py -k test_approved_job_posts_visible

==========test session starts ============
platform linux -- Python 3.8.6, pytest-5.4.1, py-1.10.0, pluggy-0.13.1 -- /usr/local/bin/python
cachedir: /home/app/.pytest_cache
django: settings: chipy_org.settings_test (from ini)
rootdir: /site/proj, inifile: pytest.ini
plugins: appmap-0.5.0, django-3.9.0
collected 9 items / 8 deselected / 1 selected

chipy_org/apps/job_board/tests/test_views.py::test_approved_job_posts_visible
PASSED          [100%]
===========1 passed, 8 deselected in 0.42s ============

The test suite will be run and AppMap files recorded from tests will be created in the tmp/appmap/pytest folder of the project.

Working with AppMaps in Visual Studio Code

Now that you have the AppMaps recorded, let's open them in the Visual Studio Code.

Open an AppMap file

  1. The recorded AppMap files are in the tmp/appmap/pytest folder of the chipy.org project.

  2. Let's open an AppMap that covers job postings on the site - only approved job posts can be visible. Navigate to the tmp/appmap/pytest folder in the file explorer and press CTRL|COMMAND P

  3. Type approved in the search box and pick the .appmap.json file. An AppMap viewer now opens.

AppMaps in action

Interact with the AppMap diagrams

  1. Hide the file explorer by clicking on its icon in the left hand icon bar.

  2. Explore the Dependency map. Click on any component and edge in the map, expand/collapse modules and HTTP endpoints, investigate their details in the left hand navigation bar

  3. Switch to the Trace view to see how the code and data flows in the application

  4. To see how AppMaps can be used for fast mastering of new-to-you code watch this demonstration video

  5. Additional information about AppMaps and their benefits can be found in the AppMap for Visual Studio Code online documentation

  6. Explore not only the previously recorded AppMaps but see how code modifications change the way the application runs. Modify the code, re-run the tests with the AppMap recording enabled and observe the changes in the dependencies and flows

  7. AppMap your application. Follow the steps outlined in this tutorial and map your application in minutes

  8. Tell your friends and colleagues. AppMaps are a fun way to learn how code works but they are also great for sharing your software designs with others

Share your AppMaps with us!

We would love to see the AppMaps of your application in the Gallery in Discord. Join us and our diverse community and share your AppMaps there!

Your AppLand team.