~~NOTOC~~

====== Xfce-Test Docker Container Quick Start Guide ======

If you want to test the current state of Xfce 4.16, you can look at [[https://github.com/schuellerf/xfce-test|xfce-test]], a [[https://hub.docker.com/r/schuellerf/xfce-test|Docker image]] by Florian Schueller, which allows you to test git master and to run automated [[https://github.com/behave/behave|Behave]] (behaviour-driven development) test scripts.


  * **[[#Installation|Installation]]**
  * **[[#Running xfce-test|Running xfce-test]]**
  * **[[#Stopping xfce-test|Stopping xfce-test]]**
  * **[[#Uninstalling xfce-test|Uninstalling xfce-test]]**
  * **[[#Reporting Bugs|Reporting Bugs]]**

[[https://github.com/schuellerf/xfce-test|Xfce Test]] is a Docker/Xephyr environment for testing the latest builds of Xfce.

**Note:** The installation, management, and troubleshooting of Docker or Xephyr(the X11 display server) is beyond the scope of this guide.

For a tutorial on using Docker, see [[https://docs.docker.com/get-started/|Getting Started]] and [[https://docs.docker.com/engine/install/linux-postinstall/|Docker Post-installation steps for Linux]]

--- 
{{https://raw.githubusercontent.com/schuellerf/xfce-test/master/main_screenshot.png?900}}

[[|Back to Top]]
----

===== Installation =====

  * Clone the xfce-test repository: ''git clone https://github.com/schuellerf/xfce-test''
  * Change to the repository directory and install the necessary components ( ''./xfce-test install'' )
    * On Xubuntu 20.04, this will install the following packages and their dependencies, if they aren’t already present - xserver-xephyr, docker.io, xvfb, jq, and curl - which will download ~71Mb and require 351Mb of space
  * Download the docker container ( ''./xfce-test pull'' ):
    * If you are having permissions issues, take a look at the [[https://docs.docker.com/engine/install/linux-postinstall/|Post-installation steps for Linux]] and the instructions for running Docker as a non-root user. 
    * This will download the Docker container part of schuellerf/xfce-test which is ~1.6Gb and require ~4.4Gb of space (as of May 2020).
  * Download a different docker container branch:
    * List the available branches: ''sudo ./xfce-test list'' ( the list also available on [[https://hub.docker.com/r/schuellerf/xfce-test/tags?page=1&ordering=last_updated|dockerhub]] )
    * Download the branch by its tag name: ''sudo TAG=[tag-name] ./xfce-test pull''

----

===== Running xfce-test =====

If xfce-test is run without any options, the xfce-test script will present output that consists of
two parts. First, the various option flags that can be used to modify the starting of the script. And, secondly, a numbered menu that appears, as follows:


| 1) install    | 7) list_local        | 13) tag    |
| 2) call    | 8) screenshots        | 14) XFSM_VERBOSE    |
| 3) pull    | 9) behave             | 15) LANG    |
| 4) start    | 10) behavevideo	    | 16) LOG    |
| 5) no-session    | 11) fulltestvideo     |17) PARALLEL_BUILDS    |
| 6) list    |12) build		     | 18) KEEP    |

At this point the user will be prompted for an option to select.
It is beyond the scope of this document enumerate the function of all of these options. It is recommended to look at the [[https://github.com/schuellerf/xfce-test#readme|xfce-test README]] as well as the scripts provided in the repository.

To simply run the container from the command line, use the command: ''./xfce-test start'' 

Below is an abbreviated example of the expected output:

<code>
You are working with the container: latest

Starting container: 737d49226369f23e1b25824131124eae9b34e728d1639a1f07e645da74c3b0d8
This container includes:
# The OK marks if building this component in the current container was successful
    OK: xfce4-dev-tools: xfce-4.16pre1
    OK: libxfce4util: xfce-4.16pre1-1-gea46c1a
    OK: xfconf: xfce-4.16pre1
    OK: libxfce4ui: xfce-4.16pre1-62-g1a31ea7
    OK: garcon: xfce-4.16pre1
    OK: exo: xfce-4.16pre1
    OK: xfce4-panel: xfce-4.16pre1
    OK: thunar: xfce-4.16pre1
NOT OK: thunar-volman: xfce-4.16pre1
NOT OK: xfce4-power-manager: xfce-4.16pre1
....
</code>

If all goes well, a graphical Xephyr window will open and a new desktop environment will be displayed. Additionally, the command line from where the xfce-test script was started will be placed in a directory on the running Docker instance. From here, you may run provided test scripts.

==== Running a Branch ====

If you have downloaded a different docker container branch by its tag name, this is the command to run it: ''sudo TAG=[tag-name] ./xfce-test start''. You can find out which branches you have installed with ''sudo ./xfce-test list_local''.

[[|Back to Top]]
----
===== Stopping xfce-test =====

''docker stop <ContainerID>'' or ''<ContainerName>'' 

The ID and name can be found by running the command ''docker ps'' outside the Docker container (i.e. on your local machine).

----

===== Uninstalling xfce-test =====

  * Remove the docker container
    * Find the schuellerf/xfce-test container’s image ID ( ''docker images -a'' )
    * Remove the container ( ''docker rmi [image’s ID]'' )
  * Remove the installed packages
    * Remove main packages ( ''sudo apt remove xserver-xephyr docker.io xvfb jq curl'' )
      * Note: you may not want to remove some of these packages if they weren't installed during the xfce-test installation
    * Remove dependencies ( ''sudo apt autoremove'' )

----

===== Reporting Bugs =====

If you encounter an Xfce bug while running the xfce-test container, please see the [[https://docs.xfce.org/contribute/bugs/start|Reporting Bugs]] page for details on reporting bugs and gathering additional information for developers.

If you encounter a bug that is related to the running of the actual xfce-test container, please see [[https://github.com/schuellerf/xfce-test/issues|xfce-test issues]] to file a bug report.


[[|Back to Top]]
----
[[ :start:|Return to Main Wiki page]]

[[ https://docs.xfce.org/contribute/start#bug_reporting_and_testing|Return to Contribute page]]