nik/FreedomBox
1
0
Fork 0
mirror of https://github.com/freedombox/FreedomBox.git synced 2026-05-27 10:44:33 +00:00
Code Issues Packages Projects Releases Wiki Activity

Clarifications: source directory within VM, and prompts marking where the commands must be executed (host or VM). Plus, some code decorations enabled (by providing languaje).

Browse Source
This commit is contained in:
Fioddor Superconcentrado 2020-04-20 16:14:17 +00:00
parent 0d059b7553
commit fa4d9fe283
1 changed files with 67 additions and 55 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

122
HACKING.md
View File

@ -11,7 +11,7 @@ can install latest versions of Git, Vagrant and VirtualBox.
1. Install Git, Vagrant and VirtualBox using apt. 1. Install Git, Vagrant and VirtualBox using apt.
``` ```bash
$ sudo apt install git virtualbox vagrant $ sudo apt install git virtualbox vagrant
``` ```
@ -25,10 +25,10 @@ can install latest versions of Git, Vagrant and VirtualBox.
2. Install Git, Vagrant and VirtualBox using Brew. 2. Install Git, Vagrant and VirtualBox using Brew.
``` ```bash
brew install git $ brew install git
brew cask install vagrant $ brew cask install vagrant
brew cask install virtualbox $ brew cask install virtualbox
``` ```
### For Windows ### For Windows
@ -40,8 +40,8 @@ can install latest versions of Git, Vagrant and VirtualBox.
2. Tell Git to use Unix line endings by running the following in Git Bash. 2. Tell Git to use Unix line endings by running the following in Git Bash.
``` ```bash
git config --global core.autocrlf input host$ git config --global core.autocrlf input
``` ```
3. Run all the following commands inside Git Bash. 3. Run all the following commands inside Git Bash.
@ -57,41 +57,49 @@ and requires about 4.5 GB of disk space.
1. Checkout FreedomBox Service (Plinth) source code using Git. 1. Checkout FreedomBox Service (Plinth) source code using Git.
``` ```bash
git clone https://salsa.debian.org/freedombox-team/plinth.git host$ git clone https://salsa.debian.org/freedombox-team/plinth.git
cd plinth host$ cd plinth
``` ```
2. To download, setup, run, and configure a VM for FreedomBox development using 2. To download, setup, run, and configure a VM for FreedomBox development using
Vagrant, simply execute in your FreedomBox Service (Plinth) development Vagrant, simply execute in your FreedomBox Service (Plinth) development
folder: folder:
``` ```bash
$ vagrant up host$ vagrant up
``` ```
3. SSH into the running vagrant box with the following command: 3. SSH into the running vagrant box with the following command:
``` ```bash
$ vagrant ssh host$ vagrant ssh
``` ```
4. Run the development version of FreedomBox Service (Plinth) from your source ## Using the Virtual Machine
directory in the virtual machine using the following command. This command
continuously deploys your code changes into the virtual machine providing a
quick feedback cycle during development.
``` Once in the virtual machine (vm) the source code is available in /vagrant directory:
$ sudo -u plinth /vagrant/run --develop
```
5. If you have changed any system configuration files during your development, ```bash
you will need to run the following to install those files properly on to the vm$ cd /vagrant
system and their changes to reflect properly. ```
``` Run the development version of FreedomBox Service (Plinth) from your source
$ sudo ./setup.py install directory in the virtual machine using the following command. This command
``` continuously deploys your code changes into the virtual machine providing a
quick feedback cycle during development.
```bash
vm$ sudo -u plinth /vagrant/run --develop
```
If you have changed any system configuration files during your development,
you will need to run the following to install those files properly on to the
system and their changes to reflect properly.
```bash
vm$ sudo ./setup.py install
```
Note: This development virtual machine has automatic upgrades disabled by Note: This development virtual machine has automatic upgrades disabled by
default. default.
@ -101,13 +109,13 @@ default.
To run all the tests: To run all the tests:
```bash ```bash
$ py.test-3 vm$ py.test-3
``` ```
Another way to run tests (not recommended): Another way to run tests (not recommended):
```bash ```bash
$ ./setup.py test vm$ ./setup.py test
``` ```
To run a specific test function, test class or test module, use pytest filtering To run a specific test function, test class or test module, use pytest filtering
@ -117,30 +125,30 @@ options. See pytest documentation for further filter options.
```bash ```bash
# Run tests in a directory # Run tests in a directory
$ py.test-3 plinth/tests vm$ py.test-3 plinth/tests
# Run tests in a module # Run tests in a module
$ py.test-3 plinth/tests/test_actions.py vm$ py.test-3 plinth/tests/test_actions.py
# Run tests of one class in test module # Run tests of one class in test module
$ py.test-3 plinth/tests/test_actions.py::TestActions vm$ py.test-3 plinth/tests/test_actions.py::TestActions
# Run one test in a class or module # Run one test in a class or module
$ py.test-3 plinth/tests/test_actions.py::TestActions::test_is_package_manager_busy vm$ py.test-3 plinth/tests/test_actions.py::TestActions::test_is_package_manager_busy
``` ```
## Running the Test Coverage Analysis ## Running the Test Coverage Analysis
To run the coverage tool: To run the coverage tool:
``` ```bash
$ py.test-3 --cov=plinth vm$ py.test-3 --cov=plinth
``` ```
To collect HTML report: To collect HTML report:
``` ```bash
$ py.test-3 --cov=plinth --cov-report=html vm$ py.test-3 --cov=plinth --cov-report=html
``` ```
Invoking this command generates a HTML report to the `htmlcov` directory. Invoking this command generates a HTML report to the `htmlcov` directory.
@ -157,7 +165,11 @@ executed (red).
#### For running tests inside the VM #### For running tests inside the VM
Run `vagrant provision --provision-with tests`. From the host, provision the virtual machine with tests:
```bash
host$ vagrant provision --provision-with tests
```
#### For running tests on host machine #### For running tests on host machine
@ -165,13 +177,13 @@ Follow the instructions below to run the tests on host machine. If you wish
perform the tests on host machine, the host machine must be based on Debian perform the tests on host machine, the host machine must be based on Debian
Buster (or later). Buster (or later).
``` ```bash
$ pip3 install splinter host$ pip3 install splinter
$ pip3 install pytest-splinter host$ pip3 install pytest-splinter
$ sudo apt install python3-pytest-bdd host$ sudo apt install python3-pytest-bdd
$ sudo apt install xvfb python3-pytest-xvfb # optional, to avoid opening browser windows host$ sudo apt install xvfb python3-pytest-xvfb # optional, to avoid opening browser windows
$ sudo apt install firefox host$ sudo apt install firefox
$ sudo apt install smbclient # optional, to test samba host$ sudo apt install smbclient # optional, to test samba
``` ```
- Install the latest version of geckodriver. It is usually a single binary which - Install the latest version of geckodriver. It is usually a single binary which
@ -206,28 +218,28 @@ tests will create the required user using FreedomBox's first boot process.
**When inside a VM you will need to target the guest VM** **When inside a VM you will need to target the guest VM**
```bash ```bash
export FREEDOMBOX_URL=https://localhost FREEDOMBOX_SAMBA_PORT=445 vm$ export FREEDOMBOX_URL=https://localhost FREEDOMBOX_SAMBA_PORT=445
``` ```
You will be running `py.test-3`. You will be running `py.test-3`.
``` ```bash
$ py.test-3 --include-functional vm$ py.test-3 --include-functional
``` ```
The full test suite can take a long time to run (more than an hour). You can The full test suite can take a long time to run (more than an hour). You can
also specify which tests to run, by specifying a mark: also specify which tests to run, by specifying a mark:
``` ```bash
$ py.test-3 -m essential --include-functional vm$ py.test-3 -m essential --include-functional
$ py.test-3 -m mediawiki --include-functional vm$ py.test-3 -m mediawiki --include-functional
``` ```
If xvfb is installed and you still want to see browser windows, use the If xvfb is installed and you still want to see browser windows, use the
`--no-xvfb` command-line argument. `--no-xvfb` command-line argument.
``` ```bash
$ py.test-3 --no-xvfb -m mediawiki --include-functional vm$ py.test-3 --no-xvfb -m mediawiki --include-functional
``` ```
## Building the Documentation Separately ## Building the Documentation Separately
@ -238,8 +250,8 @@ there. Both these are build during the installation process.
To build the documentation separately, run: To build the documentation separately, run:
``` ```bash
$ make -C doc vm$ make -C doc
``` ```
## Repository ## Repository